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 must follow our requested naming conventions.
- Your bucket must contain configuration files to tell us which Cloudinary accounts we can copy files to, when we access your bucket
- Cloudinary must 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 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 product environments (previously called 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 product environments.
To configure a Cloudinary product environment 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 product environments 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 product environment), you can add a separate file for each cloud name.
Example configuration
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.
For example,
{
"Version": "2012-10-17",
"Id": "AWSConsole-AccessLogs-Policy-BUCKETNAME-cloudinary",
"Statement": [
{
"Sid": "AWSConsoleStmt-BUCKETNAME-cloudinary",
"Effect": "Allow",
"Principal": {
"AWS": "232482882421"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::BUCKETNAME/*"
}
]
}
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:
{
"Sid": "AllowAccessForCloudinary",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::232482882421:root"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey"
],
"Resource": [
"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
]
}
For testing or POC purposes, you can also grant the relevant permission to all keys:
{
"Sid": "AllowAccessForCloudinary",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::232482882421:root"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey"
],
"Resource": "*"
}
Troubleshooting notes: If you're using KMS and Cloudinary 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.
Comments
4 comments
Ok ive done that but cant work out how to upload now using teh bucket?
Once you have taken these steps you should be able to set-up upload mapping from your Cloudinary account to your private S3 bucket, as described here (See "Lazy migration and automatic upload of S3 images").
How can I set a key to allow Cloudinary read the private files in my Bucket??
Hi Julio,
The above instructions should suffice to grant Cloudinary the permissions to read from your S3 bucket. If something isn't working for you, please open a support ticket and share the specific information so we can dig deeper.
Please sign in to leave a comment.