--- title: "Boto3 Client" slug: "boto3-client-tg" tags: ["5.5"] updated: 2026-10-27T23:00:54Z published: 2026-10-27T23:00:54Z canonical: "docs.vastdata.com/boto3-client-tg" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Boto3 Client ## Connecting to the Boto3 Client Interface To connect to the low-level client interface, use Boto3’s [client()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client) method. You must pass your VAST Cluster S3 credentials and other configurations as parameters with hardcoded values. This is the only way to specify a VAST Cluster VIP as the S3 endpoint. The following example imports the boto module and instantiates a client with the minimum configuration needed for connecting the client to your VAST Cluster S3 account over an HTTP connection: ```plaintext import boto3 s3_client = boto3.client(    's3',     use_ssl=False,     endpoint_url=         aws_access_key_id=,     aws_secret_access_key=     region_name=     config=boto3.session.Config(          signature_version='s3v4'          s3={'addressing_style': 'path'}         ) ) ``` in which: - `<ENDPOINT-URL>` can be any of the cluster's Virtual IPs, prefixed by *http://*. For example, `http://198.51.100.255`, in which *198.51.100.255* is one of the cluster's VIPs. > [!NOTE] > Note > > To retrieve the cluster's virtual lPs: > > - In the VAST Web UI, from the left navigation menu choose Network Access -> Virtual IPs to open the Virtual IPs page. It shows you which virtual IPs are configured on each CNode. - `<ACCESS-KEY>` and `<SECRET-KEY>` are your [S3 key pair](/docs-5-5/docs/managing-s3-user-permissions-tg#managing-s3-user-access-from-thevast-web-ui). - `<REGION>` can be any string. It is required if `signature_version=S3v4`. ###### For HTTPS Connection For an HTTPS connection, pass parameters as follows in the [client()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client) call: - Enable HTTPS by setting `use_ssl=True` instead of `use_ssl=False` . - If the default certificate trust store does not recognize the signer of the installed certificate, you can use the `verify` parameter to specify a non default path to the certificate trust store. If you're using a self signed certificate, you can point this to the certificate itself. For example: ```plaintext verify="path/to/client/cert.pem" ``` - Alternatively, you can use the `verify` parameter to disable verification: ```plaintext verify=False ``` ## Create a Bucket Once you have an instance of the S3 service client, you can call the [create_bucket()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.create_bucket) method on the client instance to create a bucket. > [!NOTE] > Note > > The *LocationConstraint(string)* parameter can be provided within the *CreateBucketConfiguration (dict)* parameter to specify a string representing a region where the bucket is created. If you don't specify a region, the region is set to 'vast-1'. ### Example In this example, we create a bucket called *mybucket*. ```plaintext response = s3_client.create_bucket(    Bucket='mybucket' ) ``` ## List All Buckets on the Server The [list_buckets()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.list_buckets) method returns a list of all buckets owned by the authenticated sender of the request. ### Example ```plaintext response = s3_client.list_buckets() ``` ## List Objects in a Bucket The [list_objects_v2()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.list_objects_v2) method returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. The [list_objects()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.list_objects) method is a prior version of the same method, supported for backward compatibility. ### Example This example retrieves the list of objects in the bucket "mybucket". ```plaintext response = s3_client.list_objects_v2(    Bucket='mybucket', ) ``` ## Determine if bucket exists The [head_bucket()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.head_bucket) method is used to determine if a bucket exists and if the user has permission to access it. ## Deleting a Bucket The [delete_bucket()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.delete_bucket) method deletes a bucket. All objects in the bucket must be deleted before the bucket can be deleted. ### Example ```plaintext response = s3_client.delete_bucket(    Bucket='mybucket' ) ``` ## Set ACL Permissions on a Bucket Before setting ACL permissions, we recommend you read [Managing S3 Access Control Lists (ACLs)](/docs-5-5/docs/managing-s3-access-tg#managing-s3-access-control-lists-acls). The [put_bucket_acl ()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.put_bucket_acl) method sets the permissions on a bucket using access control lists (ACL). ### Syntax Notes To grant permission to a user, specify the grantee with the following parameters: - For users on external providers only (for example, Active Directory or LDAP) pass: - The *EmailAddress* parameter and provide the user's principal name in the format *user@domain*, where *user* is the user name and *domain* is configured for an external auth provider on the cluster (LDAP, NIS). - The *Type* parameter and provide *AmazonCustomerByEmail* as its value. - For any users (including users on the VAST provider), pass: - The ID parameter and provide the user's VID as its value. > [!TIP] > Tip > > A VID is a VAST ID used in the cluster's internal user database. - The *Type* parameter and provide *CanonicalUser* as its value. To grant permission to a group, specify the grantee as follows: - For groups on external providers only (for example, Active Directory or LDAP), pass: - The *EmailAddress* parameter and provide the group in the format *group@domain*, where *group* is the group name and *domain* is configured for an external auth provider on the cluster (LDAP, NIS). - The *Type* parameter and provide *GroupLoginName* as its value. - For any groups (including groups on the VAST provider), pass: - The ID parameter and provide the group's VID as its value. > [!TIP] > Tip > > A VID is a VAST ID used in the cluster's internal user database. - The *Type* parameter and provide *CanonicalUser* as its value. To grant permission to a predefined group, specify *Group* as the 'Type' and pass the group's URI as the 'URI': - For the All Users group: 'http://acs.amazonaws.com/groups/global/AllUsers' - For the Authenticated Users group: 'http://acs.amazonaws.com/groups/global/AuthenticatedUsers' ### Examples In this example, a user with VID 3 is granted full control permission to the bucket my_bucket owned by JDoe whose VID is 2. ```plaintext response = s3_client.put_bucket_acl(      AccessControlPolicy={        'Grants': [            {                'Grantee': {                    'ID': '54',                    'Type': 'CanonicalUser',                },                'Permission': 'FULL_CONTROL'            },        ],        'Owner': {            'DisplayName': 'BSmith',            'ID': '4'        }    },    Bucket='BobsBucket', ) ``` In the following example, a group identified with an email address of *mygroup@domain.com* is granted WRITE permissions on the bucket *BobsBucket*. ```plaintext response = s3_client.put_bucket_acl(      AccessControlPolicy={        'Grants': [            {                'Grantee': {                    'Type': 'GroupLoginName',                    'EmailAddress': 'mygroup@domain.com'                },                'Permission': 'WRITE'            },        ],        'Owner': {            'DisplayName': 'BSmith',            'ID': '4'        }    },    Bucket='BobsBucket', ) ``` In the following example, the *Authenticated_Users* group is granted READ permission on the bucket *BobsBucket*. ```plaintext response = s3_client.put_bucket_acl(      AccessControlPolicy={        'Grants': [            {                'Grantee': {                    'Type': 'Group',                    'URI': 'http://acs.amazonaws.com/groups/global/AuthenticatedUsers'                },                'Permission': 'READ'            },        ],        'Owner': {            'DisplayName': 'BSmith',            'ID': '4'        }    },    Bucket='BobsBucket', ) ``` ## Return the ACL of a bucket The [get_bucket_acl()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.get_bucket_acl) method retrieves the ACL of a bucket. To learn about VAST Cluster's support for S3 ACLs, read [Managing S3 Access Control Lists (ACLs)](/docs-5-5/docs/managing-s3-access-tg#managing-s3-access-control-lists-acls). ## Return the location of a bucket The [get_bucket_location()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.get_bucket_location) method is used to return the region in which the bucket resides. If a region was specified in the [CreateBucket()](/docs-5-5/docs/boto3-client-tg#create-a-bucket) request, it is returned by this method. If no region was specified in the CreateBucket() request, the bucket region was set to 'vast-1', which is returned by this method. ### Example ```plaintext response = s3_client.get_bucket_location(    Bucket='mybucket', ) ``` ## Creating an Object The [put_object()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.put_object) method adds an object to a bucket. ## Creating a copy of an object The [copy_object()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.copy_object) method creates a copy of an object already stored on the server. ### Example In this example, we copy the object *MyObject* from the bucket *MyBucket* to the bucket *MyOtherBucket* and name the copy *MyObjectCopy*. ```plaintext response = S3_client.copy_object(    Bucket='MyOtherBucket',    CopySource='MyBucket/MyObject'    Key='MyObjectCopy', ) ``` ## Retrieving an Object The [get_object()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.get_object) method retrieves an object. To download a specified range of bytes of an object, use the *Range* parameter. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35. ### Example In this example, we download only bytes 32-64 of the object "MyObject" from the bucket "MyBucket". ```plaintext response = S3_client.get_object(    Bucket='MyBucket',    Key='MyObject',    Range='bytes=32-64', ) ``` ## Retrieving Object Metadata The [head_object()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.head_object) method retrieves metadata from an object without returning the object itself. ## Deleting an Object The [delete_object()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.delete_object) method deletes an object. ## Deleting Multiple Objects The [delete_objects()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.delete_objects) method deletes multiple objects in a bucket. ### Example ```plaintext response = s3_client.delete_objects(    Bucket='mybucket',    Delete={        'Objects': [            {'Key': 'file1'},            {'Key': 'file2'},            {'Key': 'file3'},        ],    }, ) ``` ## Set Access Control List (ACL) Permissions on an Object Before setting ACL permissions, we recommend you read [Managing S3 Access Control Lists (ACLs)](/docs-5-5/docs/managing-s3-access-tg#managing-s3-access-control-lists-acls). The [put_object_acl()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.put_object_acl) method sets the permissions on an object using access control lists (ACL). ### Syntax Notes To grant permission to a user, specify the grantee with the following parameters: - For users on external providers only (for example, Active Directory or LDAP) pass: - The *EmailAddress* parameter and provide the user's principal name in the format *user@domain*, where *user* is the user name and *domain* is configured for an external auth provider on the cluster (LDAP, NIS). - The *Type* parameter and provide *AmazonCustomerByEmail* as its value. - For any users (including users on the VAST provider), pass: - The ID parameter and provide the user's VID as its value. > [!TIP] > Tip > > A VID is a VAST ID used in the cluster's internal user database. A user VID is retrievable by running the [`user query`](/document/preview/1650610) VAST CLI command and specifying *udb* as the context of the query. The output includes the user's VID. > > The VAST CLI requires a *cluster admin* user. - The *Type* parameter and provide *CanonicalUser* as its value. To grant permission to a group, specify the grantee as follows: - For groups on external providers only (for example, Active Directory or LDAP), pass: - The *EmailAddress* parameter and provide the group in the format *group@domain*, where *group* is the group name and *domain* is configured for an external auth provider on the cluster (LDAP, NIS). - The *Type* parameter and provide *GroupLoginName* as its value. - For any groups (including groups on the VAST provider), pass: - The ID parameter and provide the group's VID as its value. > [!TIP] > Tip > > A VID is a VAST ID used in the cluster's internal user database. - The *Type* parameter and provide *CanonicalUser* as its value. To grant permission to a predefined group, specify *Group* as the 'Type' and pass the group's URI as the 'URI': - For the All Users group: 'http://acs.amazonaws.com/groups/global/AllUsers' - For the Authenticated Users group: 'http://acs.amazonaws.com/groups/global/AuthenticatedUsers' ### Examples In this example, a user with VID 3 is granted full control permission to the object *my_object* in the bucket *my_bucket* owned by *JDoe* whose VID is 2. ```plaintext response = client.put_object_acl(      AccessControlPolicy={        'Grants': [            {                'Grantee': {                    'ID': '3',                    'Type': 'CanonicalUser',                },                'Permission': 'FULL_CONTROL'            },        ],        'Owner': {            'DisplayName': 'JDoe',            'ID': '2'        }    },    Bucket='my_bucket',    Key='my_object', ) ``` In this example, the predefined AUTHENTICATED_USERS group is granted WRITE permission to the object *my_object* in the bucket *my_bucket* owned by *JDoe* whose VID is 2.. ```plaintext response = client.put_object_acl(    AccessControlPolicy={        'Grants': [            {                'Grantee': {                    'Type': 'Group',                    'URI': 'http://acs.amazonaws.com/groups/global/AuthenticatedUsers'                },                'Permission': 'WRITE'            },        ],        'Owner': {            'DisplayName': 'JDoe',            'ID': '2'        }    },    Bucket='my_bucket',    Key='my_object', ) ``` ## Return the ACL of an object The [get_object_acl()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.get_object_acl) method returns an object's ACL. To learn about VAST Cluster's support for S3 ACLs, read [Managing S3 Access Control Lists (ACLs)](/docs-5-5/docs/managing-s3-access-tg#managing-s3-access-control-lists-acls). ## Initiate a Multipart Upload The [create_multipart_upload()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.create_multipart_upload) method initiates a multipart upload and returns an upload ID. After initiating the multipart upload, you then need to [upload all parts](/docs-5-5/docs/boto3-client-tg#upload-a-part-in-a-multipart-upload) and then [complete the upload](/docs-5-5/docs/boto3-client-tg#complete-a-multipart-upload). ## Abort a Multipart Upload The [abort_multipart_upload()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.abort_multipart_upload) method aborts a multipart upload after it was initiated. After a multipart upload is aborted, no additional parts can be uploaded using the upload ID of that multipart upload. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts. ## Complete a Multipart Upload The [complete_multipart_upload()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.complete_multipart_upload) method completes a multipart upload by assembling previously uploaded parts. ## Upload a part in a Multipart Upload The [upload_part()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.upload_part) method uploads a part in a multipart upload that was already [initiated](/docs-5-5/docs/s3cmd-tg#initiate-a-multipart-upload). After uploading all parts, the upload needs to be [completed](/docs-5-5/docs/boto3-client-tg#complete-a-multipart-upload). ## Upload a part by copying data from an existing object as data source The [upload_part_copy()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.upload_part_copy) method uploads a part of a multipart upload by copying data from an existing object as data source. ## List Uploaded Parts for a Specific Multipart Upload The [list_parts()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.list_parts) method lists the parts that have been uploaded for a specific multipart upload. ## List Multipart Uploads The [list_multipart_uploads()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.list_multipart_uploads) method lists all multipart uploads in progress. ## Configure Bucket Logging Use the [put_bucket_logging()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/put_bucket_logging.html) method to configure bucket logging. The following example enables logging to a destination bucket named `c-2024-10-10-112417-595579`, where the log object keys will have a prefix of `-V/E-Test-`. Users with emails `myuser@example.com` and `onemoreuser@example.com` will have full control permissions to the log objects. ```plaintext s3.client.put_bucket_logging(    Bucket=bucket_name,    BucketLoggingStatus={        'LoggingEnabled': {            'TargetBucket': 'c-2024-10-10-112417-595579', 'TargetPrefix': '-V/E-Test-', 'TargetGrants':                 [{'Grantee': {'Type':'AmazonCustomerByEmail', 'EmailAddress': 'myuser@example.com'}, 'Permission': 'FULL_CONTROL'},                 {'Grantee': {'Type': 'AmazonCustomerByEmail', 'EmailAddress':'onemoreuser@example.com'}, 'Permission': 'FULL_CONTROL'}]        }    } ) ``` ## Return Bucket Logging Use the [get_bucket_logging()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/get_bucket_logging.html) method to configure bucket logging, for example: ```plaintext response = client.get_bucket_logging(    Bucket='mybucket', ) ``` ## Configuring Bucket Event Notifications The [put_bucket_notification_configuration()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/put_bucket_notification_configuration.html) method can be used to configure bucket event notifications, for example: ```plaintext s3.client.put_bucket_notification_configuration(    Bucket=bucket_name, NotificationConfiguration={        'TopicConfigurations': [            {'Id': 'from_S3',             'TopicArn': 'long-analysis:authority-hand',             'Events': ['s3:ObjectCreated:*'],             'Filter': {'Key': {'FilterRules': [{'Name': 'suffix', 'Value':'foo'}]}}}        ]    } ) ``` ## Return Event Notification Configuration for a Bucket The [get_bucket_notification_configuration()](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/get_bucket_notification_configuration.html) method can be used to return event notification configuration for a bucket, for example: ```plaintext s3.client.get_bucket_notification_configuration(Bucket=bucket.name) ```