openapi: 3.2.0 info: description: '# Authentication The Chef Automate API typically uses an API token passed in the header of your API request.' title: Chef Automate API Documentation Config Mgmt API termsOfService: https://www.chef.io/terms-and-conditions-of-use/ contact: url: https://www.chef.io/support/ email: support@chef.io license: name: Apache 2.0 url: https://github.com/chef/automate/blob/main/LICENSE version: version not set x-logo: altText: Chef logo url: /images/chef-automate-logo.svg servers: - url: https://automate.chef.io tags: - name: ConfigMgmt x-displayName: Nodes paths: /api/beta/cfgmgmt/rollouts/create: post: description: 'Creates a Rollout record. A rollout represents the process of nodes acquiring the latest policy revision pushed to a policy group. Authorization Action: ``` ingest:unifiedEvents:create ```' tags: - ConfigMgmt summary: CreateRollout operationId: ConfigMgmt_CreateRollout responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollout' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.CreateRollout' required: true /api/beta/cfgmgmt/rollouts/find: get: description: 'Returns the rollout for the given Chef Server/org, policy group, policy name, and policy revision Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: GetRolloutForChefRun operationId: ConfigMgmt_GetRolloutForChefRun parameters: - name: policy_name in: query schema: type: string - name: policy_group in: query schema: type: string - name: policy_revision_id in: query schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollout' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/beta/cfgmgmt/rollouts/list: get: description: 'Gives a list of rollouts Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: GetRollouts operationId: ConfigMgmt_GetRollouts parameters: - description: Filters to apply to the request for the rollouts list. name: filter in: query style: form explode: true schema: type: array items: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollouts' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/beta/cfgmgmt/rollouts/progress_by_node_segment: get: tags: - ConfigMgmt operationId: ConfigMgmt_ListNodeSegmentsWithRolloutProgress parameters: - description: Filters to apply to the request for the node segments list. name: filter in: query style: form explode: true schema: type: array items: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.NodeSegmentsWithRolloutProgress' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' summary: Config mgmt list node segments with rollout progress x-summary-source: derived /api/beta/cfgmgmt/rollouts/rollout/{rollout_id}: get: description: 'Returns the rollout with the given Id Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: GetRolloutById operationId: ConfigMgmt_GetRolloutById parameters: - name: rollout_id in: path required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollout' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/beta/cfgmgmt/rollouts/test_create: post: description: 'CreateRolloutTest is a no-op endpoint that has the same auth requirements as CreateRollout. It can be used to verify end-to-end config/connectivity for clients Authorization Action: ``` ingest:unifiedEvents:create ```' tags: - ConfigMgmt summary: CreateRolloutTest operationId: ConfigMgmt_CreateRolloutTest responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.CreateRolloutTest' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.CreateRolloutTest' required: true /api/v0/cfgmgmt/errors: get: description: 'Returns a list of the most common errors reported for infra nodes'' most recent Chef Infra Client runs. Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Errors operationId: ConfigMgmt_GetErrors parameters: - description: 'The number of results to return. If set to zero, the default size of 10 will be used. Set to a negative value for unlimited results.' name: size in: query schema: type: integer format: int32 - description: 'Filters in the request select the nodes from which the errors are collected. The same filters may be specified for this request as for other Nodes requests, with the exception of ''status'' which is not valid for this request.' name: filter in: query style: form explode: true schema: type: array items: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Errors' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/node_metadata_counts: get: description: 'For each type of field requested this returns distinct values the amount of each. For example, if the ''platform'' field is requested ''windows'' 10, ''redhat'' 5, and ''ubuntu'' 8 could be returned. The number next to each represents the number of nodes with that type of platform. Example: request ``` cfgmgmt/node_metadata_counts?type=platform&type=status ``` response ``` { "types": [ { "values": [ { "value": "mac_os_x 10.11.5", "count": 28 }, { "value": "linux 8.9", "count": 1 }, { "value": "macos 8.9", "count": 1 }, { "value": "windows 8.9", "count": 1 } ], "type": "platform" }, { "value": [ { "value": "missing", "count": 29 }, { "value": "failure", "count": 2 } ], "type": "status" } ] } ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: GetNodeMetadataCounts operationId: ConfigMgmt_GetNodeMetadataCounts parameters: - description: Types of node fields to collect value counts for. name: type in: query style: form explode: true schema: type: array items: type: string - description: Filters to apply to the counts returned. name: filter in: query style: form explode: true schema: type: array items: type: string - description: Earliest most recent check-in node information to return. name: start in: query schema: type: string - description: Latest most recent check-in node information to return. name: end in: query schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.NodeMetadataCounts' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/node_runs_daily_status_time_series: get: description: 'Provides the status of runs for each 24-hour duration. For multiple runs in one 24-hour duration, the most recent failed run will be returned. If there are no failed runs the most recent successful run will be returned. If no runs are found in the 24-hour duration, the status will be "missing" and no run information will be returned. Example: request ``` cfgmgmt/node_runs_daily_status_time_series?node_id=507bd518-5c18-4c2d-a445-60fe7dde9961&days_ago=3 ``` response ``` { "durations": [ { "start": "2020-04-25T19:00:00Z", "end": "2020-04-26T18:59:59Z", "status": "missing", "run_id": "" }, { "start": "2020-04-26T19:00:00Z", "end": "2020-04-27T18:59:59Z", "status": "missing", "run_id": "" }, { "start": "2020-04-27T19:00:00Z", "end": "2020-04-28T18:59:59Z", "status": "failure", "run_id": "b7904f41-68b5-44ec-9da6-cf2481ff8600" } ] } ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: GetNodeRunsDailyStatusTimeSeries operationId: ConfigMgmt_GetNodeRunsDailyStatusTimeSeries parameters: - description: Node ID of the runs. name: node_id in: query schema: type: string - description: Number of past days. name: days_ago in: query schema: type: integer format: int32 responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.NodeRunsDailyStatusTimeSeries' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/nodes: get: description: 'Returns a list of infra nodes that have checked in to Automate. Adding a filter makes a list of all nodes that meet the filter criteria. Filters for the same field are ORd together, while filters across different fields are ANDed together. Supports pagination, filtering (with wildcard support), and sorting. Max return payload size is 4MB, use pagination to fetch remaining data. Example: ``` cfgmgmt/nodes?pagination.page=1&pagination.size=100&sorting.field=name&sorting.order=ASC&filter=name:mySO*&filter=platform:ubun* ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Checked-in Nodes operationId: ConfigMgmt_GetNodes parameters: - description: Filters to apply to the request for nodes list. name: filter in: query style: form explode: true schema: type: array items: type: string - description: Page number of the results to return. name: pagination.page in: query schema: type: integer format: int32 - description: Amount of results to include per page. name: pagination.size in: query schema: type: integer format: int32 - description: Field to sort the list results on. name: sorting.field in: query schema: type: string - description: Order the results should be returned in. name: sorting.order in: query schema: type: string enum: - ASC - DESC default: ASC - description: Earliest most recent check-in node information to return. name: start in: query schema: type: string - description: Latest most recent check-in node information to return. name: end in: query schema: type: string responses: '200': description: A successful response. content: application/json: schema: type: array items: type: object default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/nodes/export: post: description: 'Stream nodes in JSON (default) or CSV format. Supports filtering and sorting, but not pagination. Include the value `csv` for the `output_type` parameter in the request to receive CSV formatted data. Include the value `json` for the `output_type` parameter in the request to receive JSON formatted data. Include the value `0` to sort descending. Include the value `1` to sort ascending. Example: ```''{"output_type":"csv","sorting":{"order": 1, "field": "name"},"filters":[{"status":"success","environment":"prod", "organization:chef"}]}''```' tags: - ConfigMgmt summary: NodeExport operationId: NodeExport responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.common.ExportData' text/csv: schema: $ref: '#/components/schemas/chef.automate.api.common.ExportData' requestBody: content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.NodeExport' required: true /api/v0/cfgmgmt/nodes/{node_id}/attribute: get: description: 'Returns the latest reported attributes for the provided node ID. Authorization Action: ``` infra:nodes:get ```' tags: - ConfigMgmt summary: Show Attributes operationId: ConfigMgmt_GetAttributes parameters: - description: Chef guid for the requested node. name: node_id in: path required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.NodeAttribute' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/nodes/{node_id}/runs: get: description: 'Returns a list of run metadata (id, start and end time, and status) for the provided node ID. Supports pagination. Accepts a `start` parameter to denote start date for the list and a filter of type `status`. Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Run Details operationId: ConfigMgmt_GetRuns parameters: - description: Chef guid for the node. name: node_id in: path required: true schema: type: string - description: Filters to apply to the request for runs list. name: filter in: query style: form explode: true schema: type: array items: type: string - description: Page number of the results to return. name: pagination.page in: query schema: type: integer format: int32 - description: Amount of results to include per page. name: pagination.size in: query schema: type: integer format: int32 - description: Earliest (in history) run information to return for the runs list. name: start in: query schema: type: string - description: Latest (in history) run information to return for the runs list. name: end in: query schema: type: string responses: '200': description: A successful response. content: application/json: schema: type: array items: type: object default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/nodes/{node_id}/runs/{run_id}: get: description: 'Returns the infra run report for the provided node ID and run ID. Authorization Action: ``` infra:nodes:get ```' tags: - ConfigMgmt summary: Show Node Run operationId: ConfigMgmt_GetNodeRun parameters: - description: Chef guid for the requested node. name: node_id in: path required: true schema: type: string - description: Run id for the node. name: run_id in: path required: true schema: type: string - description: End time on the node's run. name: end_time in: query schema: type: string format: date-time responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Run' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/organizations: get: description: 'Returns a list of all organizations associated with nodes that have checked in to Automate. Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Organizations operationId: ConfigMgmt_GetOrganizations responses: '200': description: A successful response. content: application/json: schema: type: array items: type: object default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/policy_revision/{revision_id}: get: description: 'Returns Policy Names with a list of cookbook names and associated policy identifiers based on a policy revision ID. Policy revision IDs are sent with an infra run report and identifies which instance of a policy the node used for this run. Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Policy Cookbooks operationId: ConfigMgmt_GetPolicyCookbooks parameters: - description: Revision id for the policy. name: revision_id in: path required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.PolicyCookbooks' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/reports/export: post: description: 'Stream node run reports in JSON (default) or CSV format. Supports filtering, but not pagination or sorting. Include the value `csv` for the `output_type` parameter in the request to receive CSV formatted data. Include the value `json` for the `output_type` parameter in the request to receive JSON formatted data. Include the node ID for the `node_id` for the reports to receive. Include the number of seconds since the Unix Epoch for the `start` and `end` fields. Example: ```''{"output_type":"csv"node_id":"80e73cf5-32eb-3556-ac99-6597274a8522","start":{"seconds":1585336095},"end":{"seconds":1585337095},"filters":[{"status":"success"}]}''```' tags: - ConfigMgmt summary: ReportExport operationId: ReportExport responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.common.ExportData' text/csv: schema: $ref: '#/components/schemas/chef.automate.api.common.ExportData' requestBody: content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.ReportExport' required: true /api/v0/cfgmgmt/source_fqdns: get: description: 'Returns a list of all Chef Infra Servers associated with nodes that have checked in to Automate. Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Associated Chef Infra Servers operationId: ConfigMgmt_GetSourceFqdns responses: '200': description: A successful response. content: application/json: schema: type: array items: type: object default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/stats/checkin_counts_timeseries: get: description: 'Returns a daily time series of unique node check-ins for the number of days requested. If `days ago` value is empty, API will return the default 1 day ago results. Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Node Checkins operationId: ConfigMgmt_GetCheckInCountsTimeSeries parameters: - description: List of filters to be applied to the time series. name: filter in: query style: form explode: true schema: type: array items: type: string - description: Number of past days to create the time series. name: days_ago in: query schema: type: integer format: int32 responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.CheckInCountsTimeSeries' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/stats/missing_node_duration_counts: get: description: 'Returns a count of missing nodes for the provided durations. Example: ``` cfgmgmt/stats/missing_node_duration_counts?durations=3d&durations=1w&durations=2w&durations=1M&durations=3M ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Missing Nodes Count operationId: ConfigMgmt_GetMissingNodeDurationCounts parameters: - description: "A valid duration is any number zero or greater with one of these characters 'h', 'd', 'w', or 'M'. \n'h' is hours\n'd' is days\n'w' is weeks\n'M' is months\nWill contain one or many." name: durations in: query style: form explode: true schema: type: array items: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.MissingNodeDurationCounts' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/stats/node_counts: get: description: 'Returns totals for failed, success, missing, and overall total infra nodes that have reported into Automate. Supports filtering. Example: ``` cfgmgmt/stats/node_counts?filter=name:mySO*&filter=platform:ubun* ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Node Status Counts operationId: ConfigMgmt_GetNodesCounts parameters: - description: List of filters to be applied to the node count results. name: filter in: query style: form explode: true schema: type: array items: type: string - description: Earliest node check-in. name: start in: query schema: type: string - description: Latest node check-in. name: end in: query schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.NodesCounts' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/stats/run_counts: get: description: 'Returns totals for failed and successful runs given a `node_id`. Example: ``` cfgmgmt/stats/run_counts?node_id=821fff07-abc9-4160-96b1-83d68ae5cfdd&start=2019-11-02 ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Run Status Totals operationId: ConfigMgmt_GetRunsCounts parameters: - description: List of filters to be applied to the run count results. name: filter in: query style: form explode: true schema: type: array items: type: string - description: Earliest (in history) run information to return for the run counts. name: start in: query schema: type: string - description: Latest (in history) run information to return for the run counts. name: end in: query schema: type: string - description: Node id associated with the run. name: node_id in: query schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.RunsCounts' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/suggestions: get: description: 'Returns possible filter values given a valid `type` parameter. All values returned until two or more characters are provided for the `text` parameter. Supports wildcard (* and ?). Example: ``` cfgmgmt/suggestions?type=environment&text=_d ``` Authorization Action: ``` infra:nodes:list ```' tags: - ConfigMgmt summary: List Filter Suggestions operationId: ConfigMgmt_GetSuggestions parameters: - description: Field for which suggestions are being returned. name: type in: query schema: type: string - description: Text to search on for the type value. name: text in: query schema: type: string - description: Filters to be applied to the results. name: filter in: query style: form explode: true schema: type: array items: type: string responses: '200': description: A successful response. content: application/json: schema: type: array items: type: object default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/telemetry/nodes/count: get: description: 'Returns the count of unique nodes with lastRun in a given time. The time duration can be between the last time Telemetry data sent and the day before the current date. If the duration 15 days duration > 15 days --> duration Authorization Action: ``` iam:introspect:getAll ```' tags: - ConfigMgmt summary: GetNodesUsageCount operationId: ConfigMgmt_GetNodesUsageCount responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.GetNodesUsageCountResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' /api/v0/cfgmgmt/telemetry/nodes/count/updated: put: tags: - ConfigMgmt summary: UpdateTelemetryReported Acknowledge API to updates the last client run… operationId: ConfigMgmt_UpdateTelemetryReported responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.UpdateTelemetryReportedResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/grpc.gateway.runtime.Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.UpdateTelemetryReportedRequest' required: true components: schemas: chef.automate.api.cfgmgmt.response.Resource: type: object properties: conditional: description: Conditional rule associated with the resource. type: string cookbook_name: description: Cookbook name associated with the resource. type: string cookbook_version: description: Version of the cookbook associated with the resource. type: string delta: description: Change diff for the resource (if it was changed during the run). type: string duration: description: Duration of the resource processing. type: string error: description: Chef Error information, available on failed runs. $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.ChefError' id: description: Id of the resource. type: string ignore_failure: description: Boolean that denotes whether or not the resource failure should be ignored. type: boolean name: description: Name for the resource. type: string recipe_name: description: Name of the recipe associated with the resource. type: string result: description: String result of the resource. type: string status: description: Status of the resource (e.g. 'up-to-date'). type: string type: description: Resource type. type: string chef.automate.api.cfgmgmt.response.PolicyCookbooks: type: object properties: cookbook_locks: description: Intentionally blank. type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.CookbookLock' policy_name: description: Name of the policy. type: string chef.automate.api.cfgmgmt.response.NodeMetadataCounts: type: object properties: types: type: array title: Field Types for a node with value counts items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.TypeCount' chef.automate.api.cfgmgmt.response.CheckInCounts: type: object properties: count: type: integer format: int32 end: type: string start: type: string total: type: integer format: int32 chef.automate.api.cfgmgmt.request.ReportExport: type: object properties: end: description: Latest (in history) run information to return for the runs list. Not required. type: string format: date-time filter: description: Filters to apply to the request for nodes list. May be empty. type: array items: type: string node_id: description: The node ID of the reports. Required. type: string output_type: description: File type, either JSON or CSV. type: string default: json enum: - json - csv start: description: Earliest (in history) run information to return for the runs list. Not required. type: string format: date-time chef.automate.api.cfgmgmt.response.CookbookLock: type: object properties: cookbook: description: Cookbook name. type: string policy_identifier: description: Policy identifier for the cookbook lock. type: string chef.automate.api.cfgmgmt.response.Errors: description: 'Errors contains a list of the most common Chef Infra error type/message combinations among nodes in the active project as filtered according to the request.' type: object properties: errors: type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.ErrorCount' chef.automate.api.common.ExportData: type: object properties: content: description: Exported reports in JSON or CSV. type: string format: byte chef.automate.api.cfgmgmt.request.CreateRollout: description: 'CreateRollout is a request to create a new Rollout. All fields have the same meaning as with the response Rollout type.' type: object properties: ci_job_id: type: string ci_job_url: type: string description: type: string policy_domain_url: type: string policy_domain_username: type: string policy_name: type: string policy_node_group: type: string policy_revision_id: type: string policy_scm_commit: type: string policy_scm_url: type: string policy_scm_web_url: type: string scm_author_email: type: string scm_author_name: type: string scm_type: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.SCMType' scm_web_type: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.request.SCMWebType' chef.automate.api.cfgmgmt.response.ErrorCount: type: object title: 'ErrorCount gives the number of occurrences (count) of the error specified by the type and message among the nodes included by the request parameters' properties: count: type: integer format: int32 error_message: type: string type: type: string chef.automate.api.cfgmgmt.request.NodeExport: type: object properties: filter: description: Filters to apply to the request for nodes list. May be empty. type: array items: type: string output_type: description: File type, either JSON or CSV. type: string default: json enum: - json - csv sorting: description: sorting parameters to apply to the returned node list. Defaults to Asc and 'name' $ref: '#/components/schemas/chef.automate.api.common.query.Sorting' chef.automate.api.cfgmgmt.response.NodeRunsDailyStatusTimeSeries: type: object properties: durations: type: array title: runs status of a 24-hour duration items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.RunDurationStatus' chef.automate.api.cfgmgmt.response.Rollout: description: 'A Rollout represents the process of distributing Chef Infra code (with Policyfiles) to a set of nodes. It''s used to track which nodes have run the latest version of the Chef Infra code assigned to them and also provide the user insights about the code by aggregating Chef Client run results according to the version of Chef Infra code applied. Metadata about the code is stored in order to provide the user with convenient references back to systems they already use (such as SCM and Ci/CD systems) to manage their code. Nodes are segmented by a triple of policy name, policy group, and policy domain URL: policy name generally describes what kind of system it is, e.g., a database server policy group generally describes where the system fits in the user''s code lifecycle, e.g., "QA" or "production." Policy groups may also represent a subset of nodes within a code lifecycle stage, such as a "production-canary" group. policy domain URL identifies the system that distributes the Chef Infra code and is the owner of the namespaces for policy name and group. E.g., a Chef Server URL with the `/organizations/:orgname` part. There is one (or zero) revision(s) of the Chef Infra code applied to any segment at a time. Rollouts track the changes to which revision of the code is applied to the node segments over time.' type: object properties: ci_job_id: description: 'If the rollout was initiated by Ci/CD or similar system, the id of the job that initiated the rollout. Should include the Ci system''s nickname or other identifying information users would need to associate the job ID to the Ci/CD system.' type: string ci_job_url: description: 'If the rollout was initiated via Ci/CD or similar system, the web URL for the job that initiated the rollout.' type: string description: description: 'A free-form description of the rollout, as given by the user. Long messages may be displayed in a truncated form in the UI. The content may be entered manually by the user or extracted from another system, for example a git commit message.' type: string end_time: description: The time that the rollout was replaced with another rollout. type: string id: description: 'The system-generated ID for this rollout. The system currently provides autoincrementing integers for the Ids.' type: string policy_domain_url: description: 'In the Chef Server case, the policy domain URL is the Chef Server URL with the `/organizations/:orgname` portion of the URL path included. In general, this can be a URL for any content storage/distribution service, as long as the combination of policy_name and policy_node_group is unique on that system. The set of nodes configured to fetch policy content from the policy_domain_url and configured with the same policy_name and policy_node_group form the target set of nodes for a rollout and are expected to apply the policy revision described by the rollout.' type: string policy_domain_username: description: 'The username of the entity who uploaded/promoted the policy code to the code host. In a Chef Server architecture, this is the name of the Chef Server user who ran the `chef push` command to upload the policy.' type: string policy_name: type: string title: The name of the policy, i.e., the `name` attribute in the Policyfile policy_node_group: description: 'The group of nodes which are targeted by the rollout. In the Chef Server case, this is the policy_group to which the user is pushing the policy.' type: string policy_revision_id: type: string title: The revision_id of the compiled policy being rolled out policy_scm_commit: description: 'The source control system''s identifier for the repository version. This should be the version where the policy''s lockfile was committed.' type: string policy_scm_url: type: string title: The URL used to obtain a copy of the source code repository policy_scm_web_url: type: string title: The URL used to view the source code repository via the web scm_author_email: description: 'The email address of the author of the most recent commit to the source code repository. In git, this is the setting `user.email`.' type: string scm_author_name: description: 'The username of the author of the most recent commit to the source code repository. In git, this is the setting `user.name`.' type: string scm_type: title: The source control system used with the policyfile $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.SCMType' scm_web_type: title: The software/service used to host the source code repository $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.SCMWebType' start_time: description: 'The time that the rollout began. Whenever a new rollout is created, it becomes the "current" rollout for its node segment; that is, any nodes that start a Chef Infra Client run will run the policy revision described by this "current" rollout. The system will populate the previously current rollout''s `end_time` attribute with the current time.' type: string grpc.gateway.runtime.Error: type: object properties: code: type: integer format: int32 details: type: array items: $ref: '#/components/schemas/google.protobuf.Any' error: type: string message: type: string chef.automate.api.cfgmgmt.response.NodeAttribute: type: object properties: all_value_count: description: Total count of attributes on the node. type: integer format: int32 automatic: description: Stringified json of the automatic attributes for the node. type: string automatic_value_count: description: Count of automatic attributes on the node. type: integer format: int32 chef_environment: description: The environment for the node. type: string default: description: Stringified json of the default attributes for the node. type: string default_value_count: description: Count of default attributes on the node. type: integer format: int32 name: description: Name of the node. type: string node_id: description: The chef_guid associated with the node. type: string normal: description: Stringified json of the normal attributes for the node. type: string normal_value_count: description: Count of normal attributes on the node. type: integer format: int32 override: description: Stringified json of the override attributes for the node. type: string override_value_count: description: Count of override attributes on the node. type: integer format: int32 run_list: description: Run list for the node. type: array items: type: string chef.automate.api.cfgmgmt.response.GetNodesUsageCountResponse: type: object properties: days_since_last_post: type: string format: int64 title: number of days since telematics was last posted node_cnt: type: string format: int64 title: unique nodes count in a duration chef.automate.api.cfgmgmt.response.CheckInCountsTimeSeries: type: object properties: counts: type: array title: List of daily checkin counts items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.CheckInCounts' chef.automate.api.cfgmgmt.response.RunDurationStatus: type: object properties: end: type: string title: End of the duration (RFC3339) run_id: type: string title: Prominent Run's ID start: type: string title: Start of the duration (RFC3339) status: type: string title: Prominent Run's status chef.automate.api.cfgmgmt.response.ChefError: type: object properties: backtrace: description: Stacktrace for the failure. type: array items: type: string class: description: Class for the error. type: string description: description: Description for the error. $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Description' message: description: Error message for the failed run. type: string chef.automate.api.cfgmgmt.response.CreateRolloutTest: type: object chef.automate.api.cfgmgmt.response.RunList: type: object properties: children: description: Intentionally blank. type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.RunList' name: description: Name of run list item. type: string skipped: description: Boolean denoting whether or not the run list item was skipped. type: boolean type: description: Type of run list item (e.g. 'recipe'). type: string version: description: Version of run list item. type: string chef.automate.api.cfgmgmt.response.Rollouts: type: object properties: rollouts: type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollout' chef.automate.api.cfgmgmt.response.CountedDuration: type: object properties: count: type: integer format: int32 title: The number of nodes for this duration duration: type: string title: Duration of the count. Example '3d' chef.automate.api.cfgmgmt.request.CreateRolloutTest: type: object chef.automate.api.cfgmgmt.response.Deprecation: type: object properties: location: description: Location of the deprecated code. type: string message: description: Message for the deprecation. type: string url: description: Url reference for the deprecation. type: string chef.automate.api.cfgmgmt.response.SCMType: type: string default: SCM_TYPE_UNSPECIFIED enum: - SCM_TYPE_UNSPECIFIED - SCM_TYPE_UNKNOWN_SCM - SCM_TYPE_GIT chef.automate.api.cfgmgmt.response.Run: type: object properties: chef_tags: description: List of tags associated with the node. type: array items: type: string chef_version: description: Chef-client version on the node. type: string cloud_provider: type: string cookbooks: description: List of cookbooks associated with the node. type: array items: type: string deprecations: description: Intentionally blank. type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Deprecation' dmi_system_manufacturer: type: string dmi_system_serial_number: type: string domain: type: string end_time: description: End time of the infra run. type: string format: date-time environment: description: The environment for the node. type: string error: description: Chef Error information, available on failed runs. $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.ChefError' expanded_run_list: description: Expanded run list for the node. $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.ExpandedRunList' fqdn: description: FQDN of the node. type: string hostname: type: string id: description: Id of the infra node run. type: string ip6address: description: IP 6 Address for the node. type: string ipaddress: description: IP Address for the node. type: string kernel_release: type: string kernel_version: type: string macaddress: type: string memory_total: type: string node_id: description: The chef_guid associated with the node. type: string node_name: description: Name of the node. type: string organization: description: The organization the node is associated with. type: string platform: description: Full platform string for the node (family + version). type: string platform_family: description: Platform family for the node. type: string platform_version: description: Platform version for the node. type: string policy_group: description: Policy group associated with the node. type: string policy_name: description: Policy name associated with the node. type: string policy_revision: description: Policy revision associated with the node. type: string projects: description: List of projects the node belongs to. type: array items: type: string recipes: description: List of recipes the node calls. type: array items: type: string resource_names: description: List of resource names for the node. type: array items: type: string resources: description: Intentionally blank. type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Resource' roles: description: List of roles associated with the node. type: array items: type: string run_list: description: Run list for the node. type: array items: type: string source: description: Source of the node run (e.g. chef-solo). type: string source_fqdn: description: Chef server associated with the node. type: string start_time: description: Start time of the infra run. type: string format: date-time status: description: Status of the infra node run. type: string tags: description: Unused field. type: array items: type: string timezone: type: string title: timezone of the node total_resource_count: description: Resource count reported on the infra node run. type: integer format: int32 updated_resource_count: description: Count of resources updated in the infra node run. type: integer format: int32 uptime_seconds: description: Count in seconds that the node has been active. type: integer format: int32 versioned_cookbooks: description: List of versioned cookbooks associated with the node. type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.VersionedCookbook' virtualization_role: type: string virtualization_system: type: string chef.automate.api.cfgmgmt.request.UpdateTelemetryReportedRequest: type: object properties: last_telemetry_reported_at: type: string title: last client run telemetry reported date chef.automate.api.cfgmgmt.response.NodeSegmentRolloutProgress: type: object properties: current_rollout_progress: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.CurrentRolloutProgress' policy_domain_url: type: string policy_name: type: string title: 'policy_name, policy_node_group, policy_domain_url make up a "compound id" for the node segment' policy_node_group: type: string previous_rollouts: type: array title: 'This is the last, say 2 or 4 rollouts before the current one (to give a total of 3 or 5)' items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.PastRolloutProgress' total_nodes: type: integer format: int32 title: total nodes in elasticsearch in the node segment chef.automate.api.cfgmgmt.response.PastRolloutProgress: type: object properties: build_link: type: string latest_run_node_count: description: 'The number of nodes in the node segment for which the last recorded CCR was part of this rollout. Note that no breakdown of success/errored is provided, since some nodes may have moved on to the current rollout and are not included in the count.' type: integer format: int32 rollout: description: Rollout is the full rollout object, but we can change this to be a subset only. $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollout' source_link: type: string chef.automate.api.cfgmgmt.response.MissingNodeDurationCounts: type: object properties: counted_durations: type: array title: List of counted durations items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.CountedDuration' chef.automate.api.cfgmgmt.response.NodeSegmentsWithRolloutProgress: description: 'A Node Segment is the set of Chef Infra nodes with a shared policy_name, policy_node_group, and policy_domain_url. NodeSegmentsWithRolloutProgress lists all of the node segments matching the request with information about the progress and status of the code rollouts for each segment.' type: object title: NodeSegmentsWithRolloutProgress properties: node_segment_rollout_progress: description: 'The NodeSegmentRolloutProgress are sorted by policy group, policy name, then domain URL.' type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.NodeSegmentRolloutProgress' google.protobuf.Any: type: object properties: type_url: type: string value: type: string format: byte chef.automate.api.cfgmgmt.response.ExpandedRunList: type: object properties: id: description: Id of the run list collection. type: string run_list: description: Intentionally blank. type: array items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.RunList' chef.automate.api.cfgmgmt.request.SCMType: type: string default: SCM_TYPE_UNSPECIFIED enum: - SCM_TYPE_UNSPECIFIED - SCM_TYPE_UNKNOWN_SCM - SCM_TYPE_GIT chef.automate.api.cfgmgmt.response.CurrentRolloutProgress: type: object properties: build_link: type: string latest_run_errored_count: type: integer format: int32 latest_run_successful_count: description: I'm assuming it's easy to get the status when we get the counts. type: integer format: int32 node_count: type: integer format: int32 title: Nodes that have run the code being rolled out thus far rollout: description: Rollout is the full rollout object, but we can change this to be a subset only. $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.Rollout' source_link: type: string chef.automate.api.cfgmgmt.response.SCMWebType: type: string default: SCM_WEB_TYPE_UNSPECIFIED enum: - SCM_WEB_TYPE_UNSPECIFIED - SCM_WEB_TYPE_UNKNOWN_SCM_WEB - SCM_WEB_TYPE_GITHUB chef.automate.api.common.query.Sorting: type: object properties: field: description: Field to sort the list results on. type: string order: description: Order the results should be returned in. $ref: '#/components/schemas/chef.automate.api.common.query.SortOrder' chef.automate.api.cfgmgmt.request.SCMWebType: type: string default: SCM_WEB_TYPE_UNSPECIFIED enum: - SCM_WEB_TYPE_UNSPECIFIED - SCM_WEB_TYPE_UNKNOWN_SCM_WEB - SCM_WEB_TYPE_GITHUB chef.automate.api.cfgmgmt.response.NodesCounts: type: object properties: failure: description: Total count of nodes that have reported in to Automate whose last run was failed. type: integer format: int32 missing: description: Total count of nodes that have been labeled as 'missing' as determined by node lifecycle settings. type: integer format: int32 success: description: Total count of nodes that have reported in to Automate whose last run was successful. type: integer format: int32 total: description: Total count of nodes that have reported in to Automate. type: integer format: int32 chef.automate.api.cfgmgmt.response.RunsCounts: type: object properties: failure: description: Total count of failed run reports that have landed in Automate for the node. type: integer format: int32 success: description: Total count of successful run reports that have landed in Automate for the node. type: integer format: int32 total: description: Total count of run reports that have landed in Automate for the node. type: integer format: int32 chef.automate.api.cfgmgmt.response.TypeCount: type: object properties: type: type: string title: The field type counted values: type: array title: Values of the field type with a count for each items: $ref: '#/components/schemas/chef.automate.api.cfgmgmt.response.ValueCount' chef.automate.api.cfgmgmt.response.ValueCount: type: object properties: count: type: integer format: int32 title: The number of this distinct value value: type: string title: The value counted chef.automate.api.cfgmgmt.response.UpdateTelemetryReportedResponse: type: object chef.automate.api.cfgmgmt.response.Description: type: object properties: sections: description: More information about the error. type: array items: type: object title: description: Title for the error description. type: string chef.automate.api.cfgmgmt.response.VersionedCookbook: type: object properties: name: description: Name of the cookbook. type: string version: description: Version of the cookbook. type: string chef.automate.api.common.query.SortOrder: type: string default: ASC enum: - ASC - DESC securitySchemes: APIToken: description: Authenticate with the Automate API using an API Token. type: apiKey name: api-token in: header x-tagGroups: - name: Compliance tags: - ReportingService - StatsService - JobsService - ProfilesService - Comp_Assets - name: Report Manager tags: - ReportManagerService - name: Infra tags: - ConfigMgmt - InfraProxy - name: Ingest tags: - ChefIngester - JobScheduler - name: Node Management tags: - NodeManagerService - NodesService - name: Event Feed tags: - EventFeedService - name: Secrets tags: - SecretsService - name: Applications tags: - service_groups - retention - ApplicationsService - name: Data Feed tags: - DatafeedService - name: Data Lifecycle tags: - DataLifecycle - name: Notifications tags: - Notifications - name: Content Delivery tags: - Cds - name: Audit and Settings tags: - UserSettingsService - name: System tags: - Gateway - Deployment - License - Telemetry - LegacyDataCollector - name: Identity tags: - users - teams - tokens - name: Access Management tags: - policies - roles - projects - rules - Authorization