:doc:`SecretsManager <../../secretsmanager>` / Client / replicate_secret_to_regions

***************************
replicate_secret_to_regions
***************************



.. py:method:: SecretsManager.Client.replicate_secret_to_regions(**kwargs)

  

  Replicates the secret to a new Regions. See `Multi-Region secrets <https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html>`__.

   

  Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters because it might be logged. For more information, see `Logging Secrets Manager events with CloudTrail <https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieve-ct-entries.html>`__.

   

  **Required permissions:** ``secretsmanager:ReplicateSecretToRegions``. If the primary secret is encrypted with a KMS key other than ``aws/secretsmanager``, you also need ``kms:Decrypt`` permission to the key. To encrypt the replicated secret with a KMS key other than ``aws/secretsmanager``, you need ``kms:GenerateDataKey`` and ``kms:Encrypt`` to the key. For more information, see `IAM policy actions for Secrets Manager <https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions>`__ and `Authentication and access control in Secrets Manager <https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/secretsmanager-2017-10-17/ReplicateSecretToRegions>`_  


  **Request Syntax**
  ::

    response = client.replicate_secret_to_regions(
        SecretId='string',
        AddReplicaRegions=[
            {
                'Region': 'string',
                'KmsKeyId': 'string'
            },
        ],
        ForceOverwriteReplicaSecret=True|False
    )
    
  :type SecretId: string
  :param SecretId: **[REQUIRED]** 

    The ARN or name of the secret to replicate.

    

  
  :type AddReplicaRegions: list
  :param AddReplicaRegions: **[REQUIRED]** 

    A list of Regions in which to replicate the secret.

    

  
    - *(dict) --* 

      A custom type that specifies a ``Region`` and the ``KmsKeyId`` for a replica secret.

      

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

        A Region code. For a list of Region codes, see `Name and code of Regions <https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints>`__.

        

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

        The ARN, key ID, or alias of the KMS key to encrypt the secret. If you don't include this field, Secrets Manager uses ``aws/secretsmanager``.

        

      
    

  :type ForceOverwriteReplicaSecret: boolean
  :param ForceOverwriteReplicaSecret: 

    Specifies whether to overwrite a secret with the same name in the destination Region. By default, secrets aren't overwritten.

    

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

    
    ::

      {
          'ARN': 'string',
          'ReplicationStatus': [
              {
                  'Region': 'string',
                  'KmsKeyId': 'string',
                  'Status': 'InSync'|'Failed'|'InProgress',
                  'StatusMessage': 'string',
                  'LastAccessedDate': datetime(2015, 1, 1)
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **ARN** *(string) --* 

        The ARN of the primary secret.

        
      

      - **ReplicationStatus** *(list) --* 

        The status of replication.

        
        

        - *(dict) --* 

          A replication object consisting of a ``RegionReplicationStatus`` object and includes a Region, KMSKeyId, status, and status message.

          
          

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

            The Region where replication occurs.

            
          

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

            Can be an ``ARN``, ``Key ID``, or ``Alias``.

            
          

          - **Status** *(string) --* 

            The status can be ``InProgress``, ``Failed``, or ``InSync``.

            
          

          - **StatusMessage** *(string) --* 

            Status message such as "*Secret with this name already exists in this region*".

            
          

          - **LastAccessedDate** *(datetime) --* 

            The date that the secret was last accessed in the Region. This field is omitted if the secret has never been retrieved in the Region.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`SecretsManager.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`SecretsManager.Client.exceptions.InvalidRequestException`

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

  
  *   :py:class:`SecretsManager.Client.exceptions.InternalServiceError`

  