#----------------------------------------------------------------------------------------------------------------------- # 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: Deployment Templates description: > A Template that provides specifies the configuration of a deployment Task - name: Activation description: > Activation represent SSM acitvation of devices as hybrid instances - name: Deployment Tasks description: > Deployment represent SSM State Manager association against devices managed as hybrid instances. paths: "/deploymentTemplates": get: tags: - Deployment Templates summary: List all available templates. operationId: listTemplates responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentTemplatesList" "404": $ref: "#/components/responses/NotFound" "/deploymentTemplates/{templateName}": parameters: - $ref: '#/components/parameters/templateName' put: tags: - Deployment Templates summary: Creates a new template or updates an exisitng template. description: > Defines a new template by specifying the type of the deployment "agentless" or "agentbased" and a source of the ansible playbook. operationId: saveTemplate requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeploymentTemplate' responses: "201": description: Created content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentTemplate" "400": $ref: "#/components/responses/BadRequest" "409": $ref: "#/components/responses/Conflict" get: tags: - Deployment Templates summary: Find a specific deployment template description: > Returns a specific deployment template by template name. operationId: getTemplate responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentTemplate" "404": $ref: "#/components/responses/NotFound" delete: tags: - Deployment Templates summary: Deletes a specific deployment template description: > Deletes a specific deployment 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: - Deployment Tasks summary: Creates a device deployments in bulk description: > Creates an SSM state manager association for a ssm managed device operationId: createDeploymentTask requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeploymentList' responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentTask" "/deploymentTasks/{deploymentTaskId}": parameters: - $ref: '#/components/parameters/deploymentTaskId' get: tags: - Deployment Tasks summary: Find a specific deployment Task by deploymentTaskId operationId: getDeploymentById responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentTask" "404": $ref: "#/components/responses/NotFound" "/deployments/{deploymentId}": parameters: - $ref: '#/components/parameters/deploymentId' get: tags: - Deployment summary: Get a deployment by its Id operationId: getDeployment responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/Deployment" "404": $ref: "#/components/responses/NotFound" patch: tags: - Deployment summary: Retry a specific deployment by deploymentId operationId: patchDeploymentById 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/RetryDeployment' responses: "200": description: OK "404": $ref: "#/components/responses/NotFound" "400": $ref: "#/components/responses/BadRequest" delete: tags: - Deployment summary: Deletes a specific deployment by deploymentId operationId: deleteDeploymentById responses: "204": description: OK "404": $ref: "#/components/responses/NotFound" "/deploymentTasks/{deploymentTaskId}/deployments": parameters: - $ref: '#/components/parameters/deploymentTaskId' get: tags: - Deployment Tasks summary: Gets the list of deployments associated with a particular deployment Task operationId: getDeploymentsByTask responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentList" "404": $ref: "#/components/responses/NotFound" "/devices/{deviceId}/deployments": parameters: - $ref: '#/components/parameters/deviceId' get: tags: - Deployment summary: Gets the list of deployments associated with a particular device operationId: getDeploymentsByDevice responses: "200": description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: "#/components/schemas/DeploymentList" "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 deploymentTaskId: name: deploymentTaskId in: path description: Deployment Task ID required: true schema: type: string deploymentId: name: deploymentId in: path description: Deployment 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: DeploymentTemplate: type: object properties: name: type: string description: Name of template. deploymentType: type: string description: type enum: [agentless, agentbased] deploymentSource: type: object properties: type: type: string description: Type of source enum: [S3] bucket: type: string description: Bucket Name of the playbook source prefix: type: string description: Bucket key prefix of the playbook source versionNo: type: number description: Auto-incrementing template version number. readOnly: true createdAt: type: string format: 'date-time' description: Date/time the template was created. readOnly: true updatedAt: type: string format: 'date-time' description: Date/time the template was updated. readOnly: true enabled: type: boolean description: Whether the template is enabled for use. description: type: string description: Description regarding the template extraVars: type: object 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 deploymentType: "agentbased" playbookSource: type: "s3" bucket: "myBucket" prefix: "device-patching/ggv2-ec2-amazonlinux2-installer-playbook.yml" extraVars: commonVar1: commonVarVal1 commonVar2: commonVarVal2 DeploymentTemplatesList: properties: tempaltes: type: array description: A list of templates items: $ref: "#/components/schemas/DeploymentTemplate" 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 deploymentType: "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" DeploymentTask: type: object properties: taskId: type: string description: deployment 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 deployments: type: array description: A list of deployments items: $ref: "#/components/schemas/Deployment" Deployment: type: object properties: taskId: type: string description: Deployment Task Id readOnly: true deviceId: type: string description: The Id of the Device readOnly: true deploymentId: type: string description: The Id of the deployment 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 deploymentTemplateName: type: string description: Deployment Template Name deploymentStatus: type: string description: The status of the deployment enum: [pending, success, failed] deploymentType: type: string description: The type of deployment enum: [agentless, agentbased] statusMessage: type: string description: Message detail pertaining to deploymentStatus 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" deploymentId: "a1b83c20-ab84-11ea-9634-37cb5e1c09aa" createdAt: "2020-06-11T01:41:12.546Z" updatedAt: "2020-06-11T01:41:12.546Z" deploymentTemplateName: "ggv2-ec2-amazonlinux2-template" deploymentStatus: "failed" deploymentType: "agentbased" statusMessage: "DEVICE_NOT_ACTIVATED_AS_HYBRID_INSTANCE" assoicationId: "a1b83c20-ab84-11ea-9634-37cb5e1c09aa" extraVars: iot_endpoint: "" iot_role_alias: "" RetryDeployment: type: object properties: deploymentStatus: type: string description: retry is the only supported patching operation supported for Retry Deployments example: deploymentStatus: "retry" DeploymentList: type: object properties: deployments: type: array description: A list of templates items: $ref: "#/components/schemas/Deployment" 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 deployments count: type: integer Error: type: object properties: message: type: string