#----------------------------------------------------------------------------------------------------------------------- # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance # with the License. A copy of the License is located at # # http://www.apache.org/licenses/LICENSE-2.0 # # or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES # OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions # and limitations under the License. #----------------------------------------------------------------------------------------------------------------------- openapi: 3.0.0 info: title: "AWS Connected Device Framework: Device Patcher" description: > Allows for patching of devices remotely utilizing SSM State Manager Associations Ansible Playbook executions on physical devices. version: 1.0.0 tags: - name: Patch Templates description: > A Template that provides specifies the configuration of a patch Task - name: Activation description: > Activation represent SSM acitvation of devices as hybrid instances - name: Patch Tasks description: > Patch represent SSM State Manager association against devices managed as hybrid instances. paths: "/patchTemplates": post: tags: - Patch Templates summary: Creates a new patch patch template description: > Defines a new template by specifying the type of the patch "agentless" or "agentbased" and a source of the ansible playbook. operationId: createTemplate requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/CreatePatchTemplate' responses: "201": description: Created "400": $ref: "#/components/responses/BadRequest" "409": $ref: "#/components/responses/Conflict" get: tags: - Patch Templates summary: List all available patch patch templates. operationId: listTemplates responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/PatchTemplatesList" "404": $ref: "#/components/responses/NotFound" "/patchTemplates/{templateName}": parameters: - $ref: '#/components/parameters/templateName' patch: tags: - Patch Templates summary: Updates a patch patch template description: > Defines a new template by specifying the type of the patch "agentless" or "agentbased" and a source of the ansible playbook. operationId: updateTemplate requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/UpdatePatchTemplate' responses: "201": description: Created "400": $ref: "#/components/responses/BadRequest" get: tags: - Patch Templates summary: Find a specific patch template description: > Returns a specific patch template by template name. operationId: getTemplate responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/PatchTemplate" "404": $ref: "#/components/responses/NotFound" delete: tags: - Patch Templates summary: Deletes a specific patch template description: > Deletes a specific patch template by template name. operationId: deleteTemplate responses: "204": description: OK "404": $ref: "#/components/responses/NotFound" "/activiations": "post": tags: - Activation summary: Creates a device activation description: > Creates an SSM activation for a managed device operationId: createActivation requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Activation' responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Activation" "/activations/{activationId}": parameters: - $ref: '#/components/parameters/activationId' get: tags: - Activation summary: Find a specific activation by Id operationId: getActivationById responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Activation" "404": $ref: "#/components/responses/NotFound" delete: tags: - Activation summary: Deletes a specific activation for a device by id operationId: deleteActivationById responses: "204": description: OK "404": $ref: "#/components/responses/NotFound" "/deployemntTasks": "post": tags: - Patch Tasks summary: Creates a device patches in bulk description: > Creates an SSM state manager association for a ssm managed device operationId: createPatchTask requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/PatchList' responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/PatchTask" "/patchTasks/{patchTaskId}": parameters: - $ref: '#/components/parameters/patchTaskId' get: tags: - Patch Tasks summary: Find a specific patch Task by patchTaskId operationId: getPatchById responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/PatchTask" "404": $ref: "#/components/responses/NotFound" "/patches/{patchId}": parameters: - $ref: '#/components/parameters/patchId' get: tags: - Patch summary: Get a patch by its Id operationId: getPatch responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Patch" "404": $ref: "#/components/responses/NotFound" patch: tags: - Patch summary: Retry a specific patch by patchId operationId: patchPatchById description: > Retries an SSM state manager association for a ssm managed device requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/RetryPatch' responses: "200": description: OK "404": $ref: "#/components/responses/NotFound" "400": $ref: "#/components/responses/BadRequest" delete: tags: - Patch summary: Deletes a specific patch by patchId operationId: deletePatchById responses: "204": description: OK "404": $ref: "#/components/responses/NotFound" "/patchTasks/{patchTaskId}/patches": parameters: - $ref: '#/components/parameters/patchTaskId' get: tags: - Patch Tasks summary: Gets the list of patches associated with a particular patch Task operationId: getPatchsByTask responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/PatchList" "404": $ref: "#/components/responses/NotFound" "/devices/{deviceId}/patches": parameters: - $ref: '#/components/parameters/deviceId' get: tags: - Patch summary: Gets the list of patches associated with a particular device operationId: getPatchsByDevice responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/PatchList" "404": $ref: "#/components/responses/NotFound" components: parameters: templateName: name: templateName in: path description: Name of template required: true schema: type: string activationId: name: activationId in: path description: Device task Id required: true schema: type: string deviceId: name: deviceId in: path description: Device Id required: true schema: type: string patchTaskId: name: patchTaskId in: path description: Patch Task ID required: true schema: type: string patchId: name: patchId in: path description: Patch ID required: true schema: type: string offset: name: offset in: query schema: type: integer minimum: 0 count: name: offset in: query schema: type: integer minimum: 0 responses: Created: description: Created successfully headers: location: schema: type: string BadRequest: description: Invalid input content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Error" NotFound: description: Not found content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Error" Conflict: description: Conflict content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Error" schemas: CreatePatchTemplate: type: object properties: playbookFile: type: string format: binary description: Path to the playbook file example: /home/user/playbook.yml name: type: string description: Name of template. patchType: type: string description: type enum: [ agentless, agentbased ] enabled: type: boolean description: Whether the template is enabled for use. description: type: string description: Description regarding the template extraVars[]: type: string description: Extra Variables that need to be passed down to the ansible exeucution as input external paramters required: - name - patchType - playbookFile example: name: ggv2 installer template patchType: "agentbased" playbookFile: "/usr/bin/device-patcher/ggv2-ec2-amazonlinux2-installer-playbook.yml" extraVars[key1]: val1 extraVars[key2]: val2 UpdatePatchTemplate: type: object properties: playbookFile: type: string format: binary description: Path to the playbook file example: /home/user/playbook.yml patchType: type: string description: type enum: [ agentless, agentbased ] enabled: type: boolean description: Whether the template is enabled for use. description: type: string description: Description regarding the template extraVars[key]: type: string description: Extra Variables that need to be passed down to the ansible exeucution as input external paramters example: name: ggv2 installer template extraVars[key1]: var1 PatchTemplate: type: object properties: name: type: string description: Name of template. playbookName: type: string description: Name of the playbook. playbookSource: type: object properties: key: type: string description: key path of where the ansible playbook file is stored in S3. bucket: type: string description: Bucket of where the ansible playbook file is stored in S3. description: Name of template. patchType: type: string description: type enum: [agentless, agentbased] enabled: type: boolean description: Whether the template is enabled for use. VersionNo: type: number description: Version of the template. description: type: string description: Description regarding the template createdAt: type: string format: 'date-time' description: Date/time the group was created. readOnly: true updatedAt: type: string format: 'date-time' description: Date/time the group was updated. readOnly: true extraVars[key]: type: object description: Extra Variables that need to be passed down to the ansible exeucution as input external paramters properties: : type: string example: name: ggv2 installer template versionNo: 1 createdAt: "2020-03-16T21:42:53.594Z" updatedAt: "2020-03-16T21:42:53.594Z" enabled: true patchType: "agentbased" playbookName: "ggv2-ec2-amazonlinux2-installer-playbook.yml" playbookSource: bucket: "myBucket" key: "device-patching/ggv2-ec2-amazonlinux2-installer-playbook.yml" extraVars: commonVar1: commonVarVal1 commonVar2: commonVarVal2 PatchTemplatesList: properties: tempaltes: type: array description: A list of templates items: $ref: "#/components/schemas/PatchTemplate" pagination: type: object properties: lastEvaulated: type: object properties: name: type: string count: type: integer example: templates: - name: ggv2 installer template versionNo: 1 createdAt: "2020-03-16T21:42:53.594Z" updatedAt: "2020-03-16T21:42:53.594Z" enabled: true patchType: "agentbased" playbookSource: type: "s3" bucket: "myBucket" prefix: "device-patching/ggv2-ec2-amazonlinux2-installer-playbook.yml" extraVars: commonVar1: commonVarVal1 commonVar2: commonVarVal2 pagination: count: 3 lastEvaluated: name: "myTemplate5" Activation: type: object properties: deviceId: type: string description: The id of target device activationId: type: string description: The id of the activaiton activationRegion: type: string description: The region where device activation has been created example: activationId: "a1102421-922f-46d5-9a85-bdbad8d90d6c" activationCode: "nxj3IC1HBquDVxM14Oqo" activationRegion: "us-east-1" PatchTask: type: object properties: taskId: type: string description: patch Task Id createdAt: type: string format: 'date-time' description: Date/time the group was created. readOnly: true updatedAt: type: string format: 'date-time' description: Date/time the group was updated. readOnly: true patches: type: array description: A list of patches items: $ref: "#/components/schemas/Patch" Patch: type: object properties: taskId: type: string description: Patch Task Id readOnly: true deviceId: type: string description: The Id of the Device readOnly: true patchId: type: string description: The Id of the patch createdAt: type: string format: 'date-time' description: Date/time the group was created. readOnly: true updatedAt: type: string format: 'date-time' description: Date/time the group was updated. readOnly: true patchTemplateName: type: string description: Patch Template Name patchStatus: type: string description: The status of the patch enum: [pending, success, failed] patchType: type: string description: The type of patch enum: [agentless, agentbased] statusMessage: type: string description: Message detail pertaining to patchStatus readOnly: true associationId: type: string description: SSM Association ID reference once the association is successfully been created readOnly: true extraVars: type: object properties: : type: string description: extra variables which are passed through to the playbook example: deviceId: "ggv2-ec2-devive1" patchId: "a1b83c20-ab84-11ea-9634-37cb5e1c09aa" createdAt: "2020-06-11T01:41:12.546Z" updatedAt: "2020-06-11T01:41:12.546Z" patchTemplateName: "ggv2-ec2-amazonlinux2-template" patchStatus: "failed" patchType: "agentbased" statusMessage: "DEVICE_NOT_ACTIVATED_AS_HYBRID_INSTANCE" associationId: "a1b83c20-ab84-11ea-9634-37cb5e1c09aa" extraVars: iot_endpoint: "" iot_role_alias: "" RetryPatch: type: object properties: patchStatus: type: string description: retry is the only supported patching operation supported for Retry Patchs example: patchStatus: "retry" PatchList: type: object properties: patches: type: array description: A list of templates items: $ref: "#/components/schemas/Patch" pagination: type: object properties: lastEvaluated: type: object properties: nextToken: type: string description: the last evauluated key token, can be used to retrieve the next batch of patches count: type: integer Error: type: object properties: message: type: string