:doc:`MQ <../../mq>` / Client / describe_broker

***************
describe_broker
***************



.. py:method:: MQ.Client.describe_broker(**kwargs)

  

  Returns information about the specified broker.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/mq-2017-11-27/DescribeBroker>`_  


  **Request Syntax**
  ::

    response = client.describe_broker(
        BrokerId='string'
    )
    
  :type BrokerId: string
  :param BrokerId: **[REQUIRED]** 

    The unique ID that Amazon MQ generates for the broker.

    

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

    
    ::

      {
          'ActionsRequired': [
              {
                  'ActionRequiredCode': 'string',
                  'ActionRequiredInfo': 'string'
              },
          ],
          'AuthenticationStrategy': 'SIMPLE'|'LDAP'|'CONFIG_MANAGED',
          'AutoMinorVersionUpgrade': True|False,
          'BrokerArn': 'string',
          'BrokerId': 'string',
          'BrokerInstances': [
              {
                  'ConsoleURL': 'string',
                  'Endpoints': [
                      'string',
                  ],
                  'IpAddress': 'string'
              },
          ],
          'BrokerName': 'string',
          'BrokerState': 'CREATION_IN_PROGRESS'|'CREATION_FAILED'|'DELETION_IN_PROGRESS'|'RUNNING'|'REBOOT_IN_PROGRESS'|'CRITICAL_ACTION_REQUIRED'|'REPLICA',
          'Configurations': {
              'Current': {
                  'Id': 'string',
                  'Revision': 123
              },
              'History': [
                  {
                      'Id': 'string',
                      'Revision': 123
                  },
              ],
              'Pending': {
                  'Id': 'string',
                  'Revision': 123
              }
          },
          'Created': datetime(2015, 1, 1),
          'DeploymentMode': 'SINGLE_INSTANCE'|'ACTIVE_STANDBY_MULTI_AZ'|'CLUSTER_MULTI_AZ',
          'EncryptionOptions': {
              'KmsKeyId': 'string',
              'UseAwsOwnedKey': True|False
          },
          'EngineType': 'ACTIVEMQ'|'RABBITMQ',
          'EngineVersion': 'string',
          'HostInstanceType': 'string',
          'LdapServerMetadata': {
              'Hosts': [
                  'string',
              ],
              'RoleBase': 'string',
              'RoleName': 'string',
              'RoleSearchMatching': 'string',
              'RoleSearchSubtree': True|False,
              'ServiceAccountUsername': 'string',
              'UserBase': 'string',
              'UserRoleName': 'string',
              'UserSearchMatching': 'string',
              'UserSearchSubtree': True|False
          },
          'Logs': {
              'Audit': True|False,
              'AuditLogGroup': 'string',
              'General': True|False,
              'GeneralLogGroup': 'string',
              'Pending': {
                  'Audit': True|False,
                  'General': True|False
              }
          },
          'MaintenanceWindowStartTime': {
              'DayOfWeek': 'MONDAY'|'TUESDAY'|'WEDNESDAY'|'THURSDAY'|'FRIDAY'|'SATURDAY'|'SUNDAY',
              'TimeOfDay': 'string',
              'TimeZone': 'string'
          },
          'PendingAuthenticationStrategy': 'SIMPLE'|'LDAP'|'CONFIG_MANAGED',
          'PendingEngineVersion': 'string',
          'PendingHostInstanceType': 'string',
          'PendingLdapServerMetadata': {
              'Hosts': [
                  'string',
              ],
              'RoleBase': 'string',
              'RoleName': 'string',
              'RoleSearchMatching': 'string',
              'RoleSearchSubtree': True|False,
              'ServiceAccountUsername': 'string',
              'UserBase': 'string',
              'UserRoleName': 'string',
              'UserSearchMatching': 'string',
              'UserSearchSubtree': True|False
          },
          'PendingSecurityGroups': [
              'string',
          ],
          'PubliclyAccessible': True|False,
          'SecurityGroups': [
              'string',
          ],
          'StorageType': 'EBS'|'EFS',
          'SubnetIds': [
              'string',
          ],
          'Tags': {
              'string': 'string'
          },
          'Users': [
              {
                  'PendingChange': 'CREATE'|'UPDATE'|'DELETE',
                  'Username': 'string'
              },
          ],
          'DataReplicationMetadata': {
              'DataReplicationCounterpart': {
                  'BrokerId': 'string',
                  'Region': 'string'
              },
              'DataReplicationRole': 'string'
          },
          'DataReplicationMode': 'NONE'|'CRDR',
          'PendingDataReplicationMetadata': {
              'DataReplicationCounterpart': {
                  'BrokerId': 'string',
                  'Region': 'string'
              },
              'DataReplicationRole': 'string'
          },
          'PendingDataReplicationMode': 'NONE'|'CRDR'
      }
      
    **Response Structure**

    

    - *(dict) --* 

      HTTP Status Code 200: OK.

      
      

      - **ActionsRequired** *(list) --* 

        Actions required for a broker.

        
        

        - *(dict) --* 

          Action required for a broker.

          
          

          - **ActionRequiredCode** *(string) --* 

            The code you can use to find instructions on the action required to resolve your broker issue.

            
          

          - **ActionRequiredInfo** *(string) --* 

            Information about the action required to resolve your broker issue.

            
      
    
      

      - **AuthenticationStrategy** *(string) --* 

        The authentication strategy used to secure the broker. The default is SIMPLE.

        
      

      - **AutoMinorVersionUpgrade** *(boolean) --* 

        Enables automatic upgrades to new patch versions for brokers as new versions are released and supported by Amazon MQ. Automatic upgrades occur during the scheduled maintenance window or after a manual broker reboot.

        
      

      - **BrokerArn** *(string) --* 

        The broker's Amazon Resource Name (ARN).

        
      

      - **BrokerId** *(string) --* 

        The unique ID that Amazon MQ generates for the broker.

        
      

      - **BrokerInstances** *(list) --* 

        A list of information about allocated brokers.

        
        

        - *(dict) --* 

          Returns information about all brokers.

          
          

          - **ConsoleURL** *(string) --* 

            The brokers web console URL.

            
          

          - **Endpoints** *(list) --* 

            The broker's wire-level protocol endpoints.

            
            

            - *(string) --* 
        
          

          - **IpAddress** *(string) --* 

            The IP address of the Elastic Network Interface (ENI) attached to the broker. Does not apply to RabbitMQ brokers.

            
      
    
      

      - **BrokerName** *(string) --* 

        The broker's name. This value must be unique in your Amazon Web Services account account, 1-50 characters long, must contain only letters, numbers, dashes, and underscores, and must not contain white spaces, brackets, wildcard characters, or special characters.

        
      

      - **BrokerState** *(string) --* 

        The broker's status.

        
      

      - **Configurations** *(dict) --* 

        The list of all revisions for the specified configuration.

        
        

        - **Current** *(dict) --* 

          The broker's current configuration.

          
          

          - **Id** *(string) --* 

            Required. The unique ID that Amazon MQ generates for the configuration.

            
          

          - **Revision** *(integer) --* 

            The revision number of the configuration.

            
      
        

        - **History** *(list) --* 

          The history of configurations applied to the broker.

          
          

          - *(dict) --* 

            A list of information about the configuration.

            
            

            - **Id** *(string) --* 

              Required. The unique ID that Amazon MQ generates for the configuration.

              
            

            - **Revision** *(integer) --* 

              The revision number of the configuration.

              
        
      
        

        - **Pending** *(dict) --* 

          The broker's pending configuration.

          
          

          - **Id** *(string) --* 

            Required. The unique ID that Amazon MQ generates for the configuration.

            
          

          - **Revision** *(integer) --* 

            The revision number of the configuration.

            
      
    
      

      - **Created** *(datetime) --* 

        The time when the broker was created.

        
      

      - **DeploymentMode** *(string) --* 

        The broker's deployment mode.

        
      

      - **EncryptionOptions** *(dict) --* 

        Encryption options for the broker.

        
        

        - **KmsKeyId** *(string) --* 

          The customer master key (CMK) to use for the A KMS (KMS). This key is used to encrypt your data at rest. If not provided, Amazon MQ will use a default CMK to encrypt your data.

          
        

        - **UseAwsOwnedKey** *(boolean) --* 

          Enables the use of an Amazon Web Services owned CMK using KMS (KMS). Set to true by default, if no value is provided, for example, for RabbitMQ brokers.

          
    
      

      - **EngineType** *(string) --* 

        The type of broker engine. Currently, Amazon MQ supports ACTIVEMQ and RABBITMQ.

        
      

      - **EngineVersion** *(string) --* 

        The broker engine version. For more information, see the `ActiveMQ version management <https://docs.aws.amazon.com//amazon-mq/latest/developer-guide/activemq-version-management.html>`__ and the `RabbitMQ version management <https://docs.aws.amazon.com//amazon-mq/latest/developer-guide/rabbitmq-version-management.html>`__ sections in the Amazon MQ Developer Guide.

        
      

      - **HostInstanceType** *(string) --* 

        The broker's instance type.

        
      

      - **LdapServerMetadata** *(dict) --* 

        The metadata of the LDAP server used to authenticate and authorize connections to the broker.

        
        

        - **Hosts** *(list) --* 

          Specifies the location of the LDAP server such as Directory Service for Microsoft Active Directory. Optional failover server.

          
          

          - *(string) --* 
      
        

        - **RoleBase** *(string) --* 

          The distinguished name of the node in the directory information tree (DIT) to search for roles or groups. For example, ou=group, ou=corp, dc=corp, dc=example, dc=com.

          
        

        - **RoleName** *(string) --* 

          Specifies the LDAP attribute that identifies the group name attribute in the object returned from the group membership query.

          
        

        - **RoleSearchMatching** *(string) --* 

          The LDAP search filter used to find roles within the roleBase. The distinguished name of the user matched by userSearchMatching is substituted into the {0} placeholder in the search filter. The client's username is substituted into the {1} placeholder. For example, if you set this option to (member=uid={1})for the user janedoe, the search filter becomes (member=uid=janedoe) after string substitution. It matches all role entries that have a member attribute equal to uid=janedoe under the subtree selected by the roleBase.

          
        

        - **RoleSearchSubtree** *(boolean) --* 

          The directory search scope for the role. If set to true, scope is to search the entire subtree.

          
        

        - **ServiceAccountUsername** *(string) --* 

          Service account username. A service account is an account in your LDAP server that has access to initiate a connection. For example, cn=admin,dc=corp, dc=example, dc=com.

          
        

        - **UserBase** *(string) --* 

          Select a particular subtree of the directory information tree (DIT) to search for user entries. The subtree is specified by a DN, which specifies the base node of the subtree. For example, by setting this option to ou=Users,ou=corp, dc=corp, dc=example, dc=com, the search for user entries is restricted to the subtree beneath ou=Users, ou=corp, dc=corp, dc=example, dc=com.

          
        

        - **UserRoleName** *(string) --* 

          Specifies the name of the LDAP attribute for the user group membership.

          
        

        - **UserSearchMatching** *(string) --* 

          The LDAP search filter used to find users within the userBase. The client's username is substituted into the {0} placeholder in the search filter. For example, if this option is set to (uid={0}) and the received username is janedoe, the search filter becomes (uid=janedoe) after string substitution. It will result in matching an entry like uid=janedoe, ou=Users,ou=corp, dc=corp, dc=example, dc=com.

          
        

        - **UserSearchSubtree** *(boolean) --* 

          The directory search scope for the user. If set to true, scope is to search the entire subtree.

          
    
      

      - **Logs** *(dict) --* 

        The list of information about logs currently enabled and pending to be deployed for the specified broker.

        
        

        - **Audit** *(boolean) --* 

          Enables audit logging. Every user management action made using JMX or the ActiveMQ Web Console is logged.

          
        

        - **AuditLogGroup** *(string) --* 

          The location of the CloudWatch Logs log group where audit logs are sent.

          
        

        - **General** *(boolean) --* 

          Enables general logging.

          
        

        - **GeneralLogGroup** *(string) --* 

          The location of the CloudWatch Logs log group where general logs are sent.

          
        

        - **Pending** *(dict) --* 

          The list of information about logs pending to be deployed for the specified broker.

          
          

          - **Audit** *(boolean) --* 

            Enables audit logging. Every user management action made using JMX or the ActiveMQ Web Console is logged.

            
          

          - **General** *(boolean) --* 

            Enables general logging.

            
      
    
      

      - **MaintenanceWindowStartTime** *(dict) --* 

        The parameters that determine the WeeklyStartTime.

        
        

        - **DayOfWeek** *(string) --* 

          Required. The day of the week.

          
        

        - **TimeOfDay** *(string) --* 

          Required. The time, in 24-hour format.

          
        

        - **TimeZone** *(string) --* 

          The time zone, UTC by default, in either the Country/City format, or the UTC offset format.

          
    
      

      - **PendingAuthenticationStrategy** *(string) --* 

        The authentication strategy that will be applied when the broker is rebooted. The default is SIMPLE.

        
      

      - **PendingEngineVersion** *(string) --* 

        The broker engine version to upgrade to. For more information, see the `ActiveMQ version management <https://docs.aws.amazon.com//amazon-mq/latest/developer-guide/activemq-version-management.html>`__ and the `RabbitMQ version management <https://docs.aws.amazon.com//amazon-mq/latest/developer-guide/rabbitmq-version-management.html>`__ sections in the Amazon MQ Developer Guide.

        
      

      - **PendingHostInstanceType** *(string) --* 

        The broker's host instance type to upgrade to. For a list of supported instance types, see `Broker instance types <https://docs.aws.amazon.com//amazon-mq/latest/developer-guide/broker.html#broker-instance-types>`__.

        
      

      - **PendingLdapServerMetadata** *(dict) --* 

        The metadata of the LDAP server that will be used to authenticate and authorize connections to the broker after it is rebooted.

        
        

        - **Hosts** *(list) --* 

          Specifies the location of the LDAP server such as Directory Service for Microsoft Active Directory. Optional failover server.

          
          

          - *(string) --* 
      
        

        - **RoleBase** *(string) --* 

          The distinguished name of the node in the directory information tree (DIT) to search for roles or groups. For example, ou=group, ou=corp, dc=corp, dc=example, dc=com.

          
        

        - **RoleName** *(string) --* 

          Specifies the LDAP attribute that identifies the group name attribute in the object returned from the group membership query.

          
        

        - **RoleSearchMatching** *(string) --* 

          The LDAP search filter used to find roles within the roleBase. The distinguished name of the user matched by userSearchMatching is substituted into the {0} placeholder in the search filter. The client's username is substituted into the {1} placeholder. For example, if you set this option to (member=uid={1})for the user janedoe, the search filter becomes (member=uid=janedoe) after string substitution. It matches all role entries that have a member attribute equal to uid=janedoe under the subtree selected by the roleBase.

          
        

        - **RoleSearchSubtree** *(boolean) --* 

          The directory search scope for the role. If set to true, scope is to search the entire subtree.

          
        

        - **ServiceAccountUsername** *(string) --* 

          Service account username. A service account is an account in your LDAP server that has access to initiate a connection. For example, cn=admin,dc=corp, dc=example, dc=com.

          
        

        - **UserBase** *(string) --* 

          Select a particular subtree of the directory information tree (DIT) to search for user entries. The subtree is specified by a DN, which specifies the base node of the subtree. For example, by setting this option to ou=Users,ou=corp, dc=corp, dc=example, dc=com, the search for user entries is restricted to the subtree beneath ou=Users, ou=corp, dc=corp, dc=example, dc=com.

          
        

        - **UserRoleName** *(string) --* 

          Specifies the name of the LDAP attribute for the user group membership.

          
        

        - **UserSearchMatching** *(string) --* 

          The LDAP search filter used to find users within the userBase. The client's username is substituted into the {0} placeholder in the search filter. For example, if this option is set to (uid={0}) and the received username is janedoe, the search filter becomes (uid=janedoe) after string substitution. It will result in matching an entry like uid=janedoe, ou=Users,ou=corp, dc=corp, dc=example, dc=com.

          
        

        - **UserSearchSubtree** *(boolean) --* 

          The directory search scope for the user. If set to true, scope is to search the entire subtree.

          
    
      

      - **PendingSecurityGroups** *(list) --* 

        The list of pending security groups to authorize connections to brokers.

        
        

        - *(string) --* 
    
      

      - **PubliclyAccessible** *(boolean) --* 

        Enables connections from applications outside of the VPC that hosts the broker's subnets.

        
      

      - **SecurityGroups** *(list) --* 

        The list of rules (1 minimum, 125 maximum) that authorize connections to brokers.

        
        

        - *(string) --* 
    
      

      - **StorageType** *(string) --* 

        The broker's storage type.

        
      

      - **SubnetIds** *(list) --* 

        The list of groups that define which subnets and IP ranges the broker can use from different Availability Zones.

        
        

        - *(string) --* 
    
      

      - **Tags** *(dict) --* 

        The list of all tags associated with this broker.

        
        

        - *(string) --* 
          

          - *(string) --* 
    
  
      

      - **Users** *(list) --* 

        The list of all broker usernames for the specified broker.

        
        

        - *(dict) --* 

          Returns a list of all broker users. Does not apply to RabbitMQ brokers.

          
          

          - **PendingChange** *(string) --* 

            The type of change pending for the broker user.

            
          

          - **Username** *(string) --* 

            Required. The username of the broker user. This value can contain only alphanumeric characters, dashes, periods, underscores, and tildes (- . _ ~). This value must be 2-100 characters long.

            
      
    
      

      - **DataReplicationMetadata** *(dict) --* 

        The replication details of the data replication-enabled broker. Only returned if dataReplicationMode is set to CRDR.

        
        

        - **DataReplicationCounterpart** *(dict) --* 

          Describes the replica/primary broker. Only returned if this broker is currently set as a primary or replica in the broker's dataReplicationRole property.

          
          

          - **BrokerId** *(string) --* 

            Required. The unique broker id generated by Amazon MQ.

            
          

          - **Region** *(string) --* 

            Required. The region of the broker.

            
      
        

        - **DataReplicationRole** *(string) --* 

          Defines the role of this broker in a data replication pair. When a replica broker is promoted to primary, this role is interchanged.

          
    
      

      - **DataReplicationMode** *(string) --* 

        Describes whether this broker is a part of a data replication pair.

        
      

      - **PendingDataReplicationMetadata** *(dict) --* 

        The pending replication details of the data replication-enabled broker. Only returned if pendingDataReplicationMode is set to CRDR.

        
        

        - **DataReplicationCounterpart** *(dict) --* 

          Describes the replica/primary broker. Only returned if this broker is currently set as a primary or replica in the broker's dataReplicationRole property.

          
          

          - **BrokerId** *(string) --* 

            Required. The unique broker id generated by Amazon MQ.

            
          

          - **Region** *(string) --* 

            Required. The region of the broker.

            
      
        

        - **DataReplicationRole** *(string) --* 

          Defines the role of this broker in a data replication pair. When a replica broker is promoted to primary, this role is interchanged.

          
    
      

      - **PendingDataReplicationMode** *(string) --* 

        Describes whether this broker will be a part of a data replication pair after reboot.

        
  
  **Exceptions**
  
  *   :py:class:`MQ.Client.exceptions.NotFoundException`

  
  *   :py:class:`MQ.Client.exceptions.BadRequestException`

  
  *   :py:class:`MQ.Client.exceptions.InternalServerErrorException`

  
  *   :py:class:`MQ.Client.exceptions.ForbiddenException`

  