Amazon CloudFormation Cloudformation Stack Set Operation API

openapi: 3.2.0
info:
  title: AWS CloudFormation Stack Set Operation API
  version: '2010-05-15'
  description: Generated from AWS's published Smithy model for AWS CloudFormation. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://cloudformation.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Stack Set Operation
paths:
  /?Action=DescribeStackSetOperation:
    post:
      operationId: DescribeStackSetOperation
      summary: Describe Stack Set Operation
      description: Returns the description of the specified StackSet operation. This API provides strongly consistent reads meaning it will always return the most up-to-date data.
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/DescribeStackSetOperationOutput'
        '404':
          description: OperationNotFoundException; StackSetNotFoundException
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/OperationNotFoundException'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - type: object
                required:
                - Action
                - Version
                properties:
                  Action:
                    type: string
                    const: DescribeStackSetOperation
                  Version:
                    type: string
                    const: '2010-05-15'
              - $ref: '#/components/schemas/DescribeStackSetOperationInput'
      tags:
      - Stack Set Operation
  /?Action=ListStackSetOperations:
    post:
      operationId: ListStackSetOperations
      summary: List Stack Set Operations
      description: Returns summary information about operations performed on a StackSet. This API provides eventually consistent reads meaning it may take some time but will eventually return the most up-to-date data.
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/ListStackSetOperationsOutput'
        '404':
          description: StackSetNotFoundException
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/StackSetNotFoundException'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - type: object
                required:
                - Action
                - Version
                properties:
                  Action:
                    type: string
                    const: ListStackSetOperations
                  Version:
                    type: string
                    const: '2010-05-15'
              - $ref: '#/components/schemas/ListStackSetOperationsInput'
      tags:
      - Stack Set Operation
  /?Action=StopStackSetOperation:
    post:
      operationId: StopStackSetOperation
      summary: Stop Stack Set Operation
      description: Stops an in-progress operation on a StackSet and its associated stack instances. StackSets will cancel all the unstarted stack instance deployments and wait for those are in-progress to complete.
      responses:
        '200':
          description: Success
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/StopStackSetOperationOutput'
        '400':
          description: InvalidOperationException
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/InvalidOperationException'
        '404':
          description: OperationNotFoundException; StackSetNotFoundException
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/OperationNotFoundException'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - type: object
                required:
                - Action
                - Version
                properties:
                  Action:
                    type: string
                    const: StopStackSetOperation
                  Version:
                    type: string
                    const: '2010-05-15'
              - $ref: '#/components/schemas/StopStackSetOperationInput'
      tags:
      - Stack Set Operation
components:
  schemas:
    StackSetOperationPreferences:
      type: object
      properties:
        RegionConcurrencyType:
          type: string
          enum:
          - SEQUENTIAL
          - PARALLEL
          description: The concurrency type of deploying StackSets operations in Regions, could be in parallel or one Region at a time.
        RegionOrder:
          type: array
          items:
            type: string
          description: The order of the Regions where you want to perform the stack operation.
        FailureToleranceCount:
          type: integer
          description: The number of accounts per Region this operation can fail in before CloudFormation stops the operation in that Region. If the operation is stopped in a Region, CloudFormation doesn't attempt the operation in any subsequent Regions. You can specify either FailureToleranceCount or FailureTolerancePercentage, but not both. By default, 0 is specified.
        FailureTolerancePercentage:
          type: integer
          description: The percentage of accounts per Region this stack operation can fail in before CloudFormation stops the operation in that Region. If the operation is stopped in a Region, CloudFormation doesn't attempt the operation in any subsequent Regions. When calculating the number of accounts based on the specified percentage, CloudFormation rounds down to the next whole number. You can specify either FailureToleranceCount or FailureTolerancePercentage, but not both. By default, 0 is specified.
        MaxConcurrentCount:
          type: integer
          description: The maximum number of accounts in which to perform this operation at one time. This can depend on the value of FailureToleranceCount depending on your ConcurrencyMode. MaxConcurrentCount is at most one more than the FailureToleranceCount if you're using STRICT_FAILURE_TOLERANCE. Note that this setting lets you specify the maximum for operations. For large deployments, under certain circumstances the actual number of accounts acted upon concurrently may be lower due to service throttling. You can specify either MaxConcurrentCount or MaxConcurrentPercentage, but not both. By default, 1 is specif
        MaxConcurrentPercentage:
          type: integer
          description: The maximum percentage of accounts in which to perform this operation at one time. When calculating the number of accounts based on the specified percentage, CloudFormation rounds down to the next whole number. This is true except in cases where rounding down would result is zero. In this case, CloudFormation sets the number as one instead. Note that this setting lets you specify the maximum for operations. For large deployments, under certain circumstances the actual number of accounts acted upon concurrently may be lower due to service throttling. You can specify either MaxConcurrentCount or
        ConcurrencyMode:
          type: string
          enum:
          - STRICT_FAILURE_TOLERANCE
          - SOFT_FAILURE_TOLERANCE
          description: 'Specifies how the concurrency level behaves during the operation execution. STRICT_FAILURE_TOLERANCE: This option dynamically lowers the concurrency level to ensure the number of failed accounts never exceeds the value of FailureToleranceCount +1. The initial actual concurrency is set to the lower of either the value of the MaxConcurrentCount, or the value of FailureToleranceCount +1. The actual concurrency is then reduced proportionally by the number of failures. This is the default behavior. If failure tolerance or Maximum concurrent accounts are set to percentages, the behavior is similar. '
    StackSetOperationStatusDetails:
      type: object
      properties:
        FailedStackInstancesCount:
          type: integer
          description: The number of stack instances for which the StackSet operation failed.
    InvalidOperationException:
      type: object
      properties:
        Message:
          type: string
    StackSetOperationSummary:
      type: object
      properties:
        OperationId:
          type: string
          description: The unique ID of the StackSet operation.
        Action:
          type: string
          enum:
          - CREATE
          - UPDATE
          - DELETE
          - DETECT_DRIFT
          description: 'The type of operation: CREATE, UPDATE, or DELETE. Create and delete operations affect only the specified stack instances that are associated with the specified StackSet. Update operations affect both the StackSet itself and all associated StackSet instances.'
        Status:
          type: string
          enum:
          - RUNNING
          - SUCCEEDED
          - FAILED
          - STOPPING
          - STOPPED
          - QUEUED
          description: 'The overall status of the operation. FAILED: The operation exceeded the specified failure tolerance. The failure tolerance value that you''ve set for an operation is applied for each Region during stack create and update operations. If the number of failed stacks within a Region exceeds the failure tolerance, the status of the operation in the Region is set to FAILED. This in turn sets the status of the operation as a whole to FAILED, and CloudFormation cancels the operation in any remaining Regions. QUEUED: [Service-managed permissions] For automatic deployments that require a sequence of oper'
        CreationTimestamp:
          type: string
          format: date-time
          description: The time at which the operation was initiated. Note that the creation times for the StackSet operation might differ from the creation time of the individual stacks themselves. This is because CloudFormation needs to perform preparatory work for the operation, such as dispatching the work to the requested Regions, before actually creating the first stacks.
        EndTimestamp:
          type: string
          format: date-time
          description: The time at which the StackSet operation ended, across all accounts and Regions specified. Note that this doesn't necessarily mean that the StackSet operation was successful, or even attempted, in each account or Region.
        StatusReason:
          type: string
          description: The status of the operation in details.
        StatusDetails:
          $ref: '#/components/schemas/StackSetOperationStatusDetails'
        OperationPreferences:
          $ref: '#/components/schemas/StackSetOperationPreferences'
    DescribeStackSetOperationInput:
      type: object
      properties:
        StackSetName:
          type: string
          description: The name or the unique stack ID of the StackSet for the stack operation.
        OperationId:
          type: string
          description: The unique ID of the StackSet operation.
        CallAs:
          type: string
          enum:
          - SELF
          - DELEGATED_ADMIN
          description: '[Service-managed permissions] Specifies whether you are acting as an account administrator in the organization''s management account or as a delegated administrator in a member account. By default, SELF is specified. Use SELF for StackSets with self-managed permissions. If you are signed in to the management account, specify SELF. If you are signed in to a delegated administrator account, specify DELEGATED_ADMIN. Your Amazon Web Services account must be registered as a delegated administrator in the management account. For more information, see Register a delegated administrator in the CloudFor'
      required:
      - StackSetName
      - OperationId
    ListStackSetOperationsOutput:
      type: object
      properties:
        Summaries:
          type: array
          items:
            $ref: '#/components/schemas/StackSetOperationSummary'
          description: A list of StackSetOperationSummary structures that contain summary information about operations for the specified StackSet.
        NextToken:
          type: string
          description: If the request doesn't return all results, NextToken is set to a token. To retrieve the next set of results, call ListOperationResults again and assign that token to the request object's NextToken parameter. If there are no remaining results, NextToken is set to null.
    ListStackSetOperationsInput:
      type: object
      properties:
        StackSetName:
          type: string
          description: The name or unique ID of the StackSet that you want to get operation summaries for.
        NextToken:
          type: string
          description: The token for the next set of items to return. (You received this token from a previous call.)
        MaxResults:
          type: integer
          description: The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
        CallAs:
          type: string
          enum:
          - SELF
          - DELEGATED_ADMIN
          description: '[Service-managed permissions] Specifies whether you are acting as an account administrator in the organization''s management account or as a delegated administrator in a member account. By default, SELF is specified. Use SELF for StackSets with self-managed permissions. If you are signed in to the management account, specify SELF. If you are signed in to a delegated administrator account, specify DELEGATED_ADMIN. Your Amazon Web Services account must be registered as a delegated administrator in the management account. For more information, see Register a delegated administrator in the CloudFor'
      required:
      - StackSetName
    StackSetOperation:
      type: object
      properties:
        OperationId:
          type: string
          description: The unique ID of a StackSet operation.
        StackSetId:
          type: string
          description: The ID of the StackSet.
        Action:
          type: string
          enum:
          - CREATE
          - UPDATE
          - DELETE
          - DETECT_DRIFT
          description: 'The type of StackSet operation: CREATE, UPDATE, or DELETE. Create and delete operations affect only the specified stack instances that are associated with the specified StackSet. Update operations affect both the StackSet itself, in addition to all associated stack instances.'
        Status:
          type: string
          enum:
          - RUNNING
          - SUCCEEDED
          - FAILED
          - STOPPING
          - STOPPED
          - QUEUED
          description: 'The status of the operation. FAILED: The operation exceeded the specified failure tolerance. The failure tolerance value that you''ve set for an operation is applied for each Region during stack create and update operations. If the number of failed stacks within a Region exceeds the failure tolerance, the status of the operation in the Region is set to FAILED. This in turn sets the status of the operation as a whole to FAILED, and CloudFormation cancels the operation in any remaining Regions. QUEUED: [Service-managed permissions] For automatic deployments that require a sequence of operations, '
        OperationPreferences:
          $ref: '#/components/schemas/StackSetOperationPreferences'
        RetainStacks:
          type: boolean
          description: For StackSet operations of action type DELETE, specifies whether to remove the stack instances from the specified StackSet, but doesn't delete the stacks. You can't re-associate a retained stack, or add an existing, saved stack to a new StackSet.
        AdministrationRoleARN:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role used to perform this StackSet operation. Use customized administrator roles to control which users or groups can manage specific StackSets within the same administrator account. For more information, see Grant self-managed permissions in the CloudFormation User Guide.
        ExecutionRoleName:
          type: string
          description: The name of the IAM execution role used to create or update the StackSet. Use customized execution roles to control which stack resources users and groups can include in their StackSets.
        CreationTimestamp:
          type: string
          format: date-time
          description: The time at which the operation was initiated. Note that the creation times for the stack set operation might differ from the creation time of the individual stacks themselves. This is because CloudFormation needs to perform preparatory work for the operation, such as dispatching the work to the requested Regions, before actually creating the first stacks.
        EndTimestamp:
          type: string
          format: date-time
          description: The time at which the StackSet operation ended, across all accounts and Regions specified. Note that this doesn't necessarily mean that the StackSet operation was successful, or even attempted, in each account or Region.
        DeploymentTargets:
          $ref: '#/components/schemas/DeploymentTargets'
        StackSetDriftDetectionDetails:
          $ref: '#/components/schemas/StackSetDriftDetectionDetails'
        StatusReason:
          type: string
          description: The status of the operation in details.
        StatusDetails:
          $ref: '#/components/schemas/StackSetOperationStatusDetails'
    OperationNotFoundException:
      type: object
      properties:
        Message:
          type: string
    StackSetDriftDetectionDetails:
      type: object
      properties:
        DriftStatus:
          type: string
          enum:
          - DRIFTED
          - IN_SYNC
          - NOT_CHECKED
          description: 'Status of the StackSet''s actual configuration compared to its expected template and parameter configuration. DRIFTED: One or more of the stack instances belonging to the StackSet differs from the expected template and parameter configuration. A stack instance is considered to have drifted if one or more of the resources in the associated stack have drifted. NOT_CHECKED: CloudFormation hasn''t checked the StackSet for drift. IN_SYNC: All of the stack instances belonging to the StackSet stack match the expected template and parameter configuration.'
        DriftDetectionStatus:
          type: string
          enum:
          - COMPLETED
          - FAILED
          - PARTIAL_SUCCESS
          - IN_PROGRESS
          - STOPPED
          description: 'The status of the StackSet drift detection operation. COMPLETED: The drift detection operation completed without failing on any stack instances. FAILED: The drift detection operation exceeded the specified failure tolerance. PARTIAL_SUCCESS: The drift detection operation completed without exceeding the failure tolerance for the operation. IN_PROGRESS: The drift detection operation is currently being performed. STOPPED: The user has canceled the drift detection operation.'
        LastDriftCheckTimestamp:
          type: string
          format: date-time
          description: Most recent time when CloudFormation performed a drift detection operation on the StackSet. This value will be NULL for any StackSet that drift detection hasn't yet been performed on.
        TotalStackInstancesCount:
          type: integer
          description: 'The total number of stack instances belonging to this StackSet. The total number of stack instances is equal to the total of: Stack instances that match the StackSet configuration. Stack instances that have drifted from the StackSet configuration. Stack instances where the drift detection operation has failed. Stack instances currently being checked for drift.'
        DriftedStackInstancesCount:
          type: integer
          description: The number of stack instances that have drifted from the expected template and parameter configuration of the StackSet. A stack instance is considered to have drifted if one or more of the resources in the associated stack don't match their expected configuration.
        InSyncStackInstancesCount:
          type: integer
          description: The number of stack instances which match the expected template and parameter configuration of the StackSet.
        InProgressStackInstancesCount:
          type: integer
          description: The number of stack instances that are currently being checked for drift.
        FailedStackInstancesCount:
          type: integer
          description: The number of stack instances for which the drift detection operation failed.
    StopStackSetOperationInput:
      type: object
      properties:
        StackSetName:
          type: string
          description: The name or unique ID of the StackSet that you want to stop the operation for.
        OperationId:
          type: string
          description: The ID of the stack operation.
        CallAs:
          type: string
          enum:
          - SELF
          - DELEGATED_ADMIN
          description: Specifies whether you are acting as an account administrator in the organization's management account or as a delegated administrator in a member account. Valid only if the StackSet uses service-managed permissions. By default, SELF is specified. Use SELF for StackSets with self-managed permissions. If you are signed in to the management account, specify SELF. If you are signed in to a delegated administrator account, specify DELEGATED_ADMIN. Your Amazon Web Services account must be registered as a delegated administrator in the management account. For more information, see Register a delegate
      required:
      - StackSetName
      - OperationId
    DeploymentTargets:
      type: object
      properties:
        Accounts:
          type: array
          items:
            type: string
          description: The Amazon Web Services account IDs where you want to perform stack operations. How these accounts are used depends on the AccountFilterType property. If you have many account numbers, you can provide those accounts using the AccountsUrl property instead.
        AccountsUrl:
          type: string
          description: The Amazon S3 URL path to a file that contains a list of Amazon Web Services account IDs. The file format must be either .csv or .txt, and the data can be comma-separated or new-line-separated. There is currently a 10MB limit for the data (approximately 800,000 accounts). This property serves the same purpose as Accounts but allows you to specify a large number of accounts.
        OrganizationalUnitIds:
          type: array
          items:
            type: string
          description: The organization root ID or organizational unit (OU) IDs where you want to perform stack operations. CloudFormation will perform operations on accounts within these OUs and their child OUs.
        AccountFilterType:
          type: string
          enum:
          - NONE
          - INTERSECTION
          - DIFFERENCE
          - UNION
          description: 'Refines which accounts will have stack operations performed on them by specifying how to use the Accounts and OrganizationalUnitIds properties together. The following values determine how CloudFormation selects target accounts: INTERSECTION: Performs stack operations only on specific individual accounts within the selected OUs. Only accounts that are both specified in the Accounts property and belong to the specified OUs will be targeted. DIFFERENCE: Performs stack operations on all accounts in the selected OUs except for specific accounts listed in the Accounts property. This enables you to e'
    StackSetNotFoundException:
      type: object
      properties:
        Message:
          type: string
    DescribeStackSetOperationOutput:
      type: object
      properties:
        StackSetOperation:
          $ref: '#/components/schemas/StackSetOperation'
    StopStackSetOperationOutput:
      type: object
      properties: {}
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: cloudformation
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/cloudformation/service/2010-05-15/cloudformation-2010-05-15.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)