Several Cloudinary features can be used to read assets from your existing S3 bucket.
Most commonly, this is if you're using our Programmable Media product, and uploading files from S3 directly using our APIs, SDKs, or Upload Widget, or via our Auto-Upload feature.
In order for Cloudinary to be able to read assets that are stored on a private S3 bucket when working with our Programmable Media or DAM products, there are three prerequisites:
- The name of the S3 bucket should follow our requested naming conventions.
- Your bucket should contain configuration files to tell us which Cloudinary accounts we can copy files to, when we access your bucket
- Cloudinary should be given permission to access files in the bucket using the S3 bucket policy.
With those steps completed, Cloudinary will be able to access files from your bucket and upload them to your account.
Note that if you're using our Media Optimizer product with an S3 bucket as a Media Source, our permission to access the bucket is provided is configured via a different method, where you specify an Access key and Secret key In the Media Source configuration.
Configuring which Cloudinary accounts will use files from the bucket
Configuring which Cloudinary [sub] accounts will be able to access files from your bucket is performed by creating specially-named files in a folder in the S3 bucket. When Cloudinary reads the folder and sees the filenames inside, it allows us to verify that the bucket owner intends for files in this bucket to be usable with the specified Cloudinary accounts.
To configure a Cloudinary account which should be able to access files in the bucket:
- Create or upload a file in the bucket, in the folder ".wellknown/cloudinary"
- The name of the file should be the cloud name of the Cloudinary [sub] accounts which should be able to use files in this bucket.
- If you want this bucket to be usable by more than one Cloudinary account (or sub-account), you can add a separate file for each cloud name.
This example shows a file created in a bucket named 'demobucket', which allows the Cloudinary account with cloud name 'demo' to access files from the bucket.
Giving Cloudinary permission to read the bucket
You must also grant Cloudinary permission to read the contents of the S3 bucket using Amazon's APIs. Permission assignment can be done using Amazon's AWS S3 Console by following this procedure:
- Select the relevant bucket.
- Select the "Permissions" tab (or click on the bucket and select Permissions | Bucket Policy).
- Paste the following policy-text (change
"BUCKETNAME"to the name of your bucket). If a policy already exists, append the new statement to the existing policy.
Additional configuration if using Key Management Service (KMS)
If you use KMS, it's recommended that you grant access by specifying the ARN of the KMS key(s) used to manage the bucket, by adding an additional statement to your KMS key definition.
Under the section STATEMENT, add the following:
For testing or POC purposes, you can also grant the relevant permission to all keys:
Troubleshooting notes: If you're using KMS and we still can't access files in your bucket despite the policy appearing to be correct, please verify that the key we've been granted permission to is indeed the same key used to protect the objects in S3. This can be seen in the object metadata.
If the keys are changed in the future, the policy must also be updated so that Cloudinary can use the new keys.