:doc:`ECS <../../ecs>` / Client / submit_task_state_change

************************
submit_task_state_change
************************



.. py:method:: ECS.Client.submit_task_state_change(**kwargs)

  

  .. note::

    

    This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent.

    

   

  Sent to acknowledge that a task changed states.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ecs-2014-11-13/SubmitTaskStateChange>`_  


  **Request Syntax**
  ::

    response = client.submit_task_state_change(
        cluster='string',
        task='string',
        status='string',
        reason='string',
        containers=[
            {
                'containerName': 'string',
                'imageDigest': 'string',
                'runtimeId': 'string',
                'exitCode': 123,
                'networkBindings': [
                    {
                        'bindIP': 'string',
                        'containerPort': 123,
                        'hostPort': 123,
                        'protocol': 'tcp'|'udp',
                        'containerPortRange': 'string',
                        'hostPortRange': 'string'
                    },
                ],
                'reason': 'string',
                'status': 'string'
            },
        ],
        attachments=[
            {
                'attachmentArn': 'string',
                'status': 'string'
            },
        ],
        managedAgents=[
            {
                'containerName': 'string',
                'managedAgentName': 'ExecuteCommandAgent',
                'status': 'string',
                'reason': 'string'
            },
        ],
        pullStartedAt=datetime(2015, 1, 1),
        pullStoppedAt=datetime(2015, 1, 1),
        executionStoppedAt=datetime(2015, 1, 1)
    )
    
  :type cluster: string
  :param cluster: 

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the task.

    

  
  :type task: string
  :param task: 

    The task ID or full ARN of the task in the state change request.

    

  
  :type status: string
  :param status: 

    The status of the state change request.

    

  
  :type reason: string
  :param reason: 

    The reason for the state change request.

    

  
  :type containers: list
  :param containers: 

    Any containers that's associated with the state change request.

    

  
    - *(dict) --* 

      An object that represents a change in state for a container.

      

    
      - **containerName** *(string) --* 

        The name of the container.

        

      
      - **imageDigest** *(string) --* 

        The container image SHA 256 digest.

        

      
      - **runtimeId** *(string) --* 

        The ID of the Docker container.

        

      
      - **exitCode** *(integer) --* 

        The exit code for the container, if the state change is a result of the container exiting.

        

      
      - **networkBindings** *(list) --* 

        Any network bindings that are associated with the container.

        

      
        - *(dict) --* 

          Details on the network bindings between a container and its host container instance. After a task reaches the ``RUNNING`` status, manual and automatic host and container port assignments are visible in the ``networkBindings`` section of `DescribeTasks <https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html>`__ API responses.

          

        
          - **bindIP** *(string) --* 

            The IP address that the container is bound to on the container instance.

            

          
          - **containerPort** *(integer) --* 

            The port number on the container that's used with the network binding.

            

          
          - **hostPort** *(integer) --* 

            The port number on the host that's used with the network binding.

            

          
          - **protocol** *(string) --* 

            The protocol used for the network binding.

            

          
          - **containerPortRange** *(string) --* 

            The port number range on the container that's bound to the dynamically mapped host port range.

             

            The following rules apply when you specify a ``containerPortRange``:

             

            
            * You must use either the ``bridge`` network mode or the ``awsvpc`` network mode.
             
            * This parameter is available for both the EC2 and Fargate launch types.
             
            * This parameter is available for both the Linux and Windows operating systems.
             
            * The container instance must have at least version 1.67.0 of the container agent and at least version 1.67.0-1 of the ``ecs-init`` package
             
            * You can specify a maximum of 100 port ranges per container.
             
            * You do not specify a ``hostPortRange``. The value of the ``hostPortRange`` is set as follows: 

              
              * For containers in a task with the ``awsvpc`` network mode, the ``hostPortRange`` is set to the same value as the ``containerPortRange``. This is a static mapping strategy.
               
              * For containers in a task with the ``bridge`` network mode, the Amazon ECS agent finds open host ports from the default ephemeral range and passes it to docker to bind them to the container ports.
              

            
             
            * The ``containerPortRange`` valid values are between 1 and 65535.
             
            * A port can only be included in one port mapping per container.
             
            * You cannot specify overlapping port ranges.
             
            * The first port in the range must be less than last port in the range.
             
            * Docker recommends that you turn off the docker-proxy in the Docker daemon config file when you have a large number of ports. For more information, see `Issue #11185 <https://github.com/moby/moby/issues/11185>`__ on the Github website. For information about how to turn off the docker-proxy in the Docker daemon config file, see `Docker daemon <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bootstrap_container_instance.html#bootstrap_docker_daemon>`__ in the *Amazon ECS Developer Guide*.
            

             

            You can call `DescribeTasks <https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html>`__ to view the ``hostPortRange`` which are the host ports that are bound to the container ports.

            

          
          - **hostPortRange** *(string) --* 

            The port number range on the host that's used with the network binding. This is assigned is assigned by Docker and delivered by the Amazon ECS agent.

            

          
        
    
      - **reason** *(string) --* 

        The reason for the state change.

        

      
      - **status** *(string) --* 

        The status of the container.

        

      
    

  :type attachments: list
  :param attachments: 

    Any attachments associated with the state change request.

    

  
    - *(dict) --* 

      An object representing a change in state for a task attachment.

      

    
      - **attachmentArn** *(string) --* **[REQUIRED]** 

        The Amazon Resource Name (ARN) of the attachment.

        

      
      - **status** *(string) --* **[REQUIRED]** 

        The status of the attachment.

        

      
    

  :type managedAgents: list
  :param managedAgents: 

    The details for the managed agent that's associated with the task.

    

  
    - *(dict) --* 

      An object representing a change in state for a managed agent.

      

    
      - **containerName** *(string) --* **[REQUIRED]** 

        The name of the container that's associated with the managed agent.

        

      
      - **managedAgentName** *(string) --* **[REQUIRED]** 

        The name of the managed agent.

        

      
      - **status** *(string) --* **[REQUIRED]** 

        The status of the managed agent.

        

      
      - **reason** *(string) --* 

        The reason for the status of the managed agent.

        

      
    

  :type pullStartedAt: datetime
  :param pullStartedAt: 

    The Unix timestamp for the time when the container image pull started.

    

  
  :type pullStoppedAt: datetime
  :param pullStoppedAt: 

    The Unix timestamp for the time when the container image pull completed.

    

  
  :type executionStoppedAt: datetime
  :param executionStoppedAt: 

    The Unix timestamp for the time when the task execution stopped.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'acknowledgment': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **acknowledgment** *(string) --* 

        Acknowledgement of the state change.

        
  
  **Exceptions**
  
  *   :py:class:`ECS.Client.exceptions.ServerException`

  
  *   :py:class:`ECS.Client.exceptions.ClientException`

  
  *   :py:class:`ECS.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`ECS.Client.exceptions.InvalidParameterException`

  