Skip to main content
Version: v1

Caching S3 Objects

To cache objects from S3 buckets, s3_resource (S3 resources) and s3_bucket (S3 buckets) objects are created and configured to match the client’s buckets.
When creating an s3_resource, you must select an S3 provider (s3_provider) that this resource belongs to. Below is a description of each object.

S3 Providers​

Arviol supports caching objects from a limited list of S3 providers.
To retrieve the list, use the appropriate API method.
Structure of an s3_provider object:

{
    "id": "integer, Provider id",
    "name": "string, Provider name",
    "bucket_name_location": "string, Designates whether a bucket name is a part of a hostname or path",
    "min_bucket_name_length": "integer, Minimum bucket name",
    "max_bucket_name_length": "integer, Maximum bucket name",
    "bucket_name_regex_pattern": "string, Regular expression for bucket name validation",
    "bucket_naming_rule_description": "string, References or description for bucket naming rules",
    "hostname_regex_pattern": "string, Regular expression for hostname validation",
    "protocol_regex_pattern": "string, Regular expression for protocol validation",
    "port_regex_pattern": "string, Regular expression for port validation",
    "url_naming_rule_description": "string, References or description for hostname naming rules"
}

S3 Resources​

The s3_resource object forms the basis for the client-added buckets.
It is required to set up the interaction between the client's original buckets and the ones created in the system.

To create an S3 resource, specify the following provider parameters:

  • its ID in the system
  • protocol (http or https)
  • host
  • port

A dedicated API method is available for validating these parameters.

After creation, the cdn_s3_domain field in the resource object will contain a generated unique CDN domain, e.g. https://s128.s3-clients.arviol.com.
Requests to this domain will be served from cache.

Managing S3 Resources​

Since the S3 resource is the base for buckets, updating or deleting it affects all connected buckets.
When an S3 resource is updated, all final URLs for accessing bucket objects change.
When deleted, the resource and all its buckets are removed.

info

Creating, updating, and deleting S3 resources is handled via background tasks.

S3 Buckets​

Once an S3 resource is created, you can create buckets by linking them to the resource.
Each resource can have up to 20 buckets.

headers — a list of response headers that the CDN injects when serving bucket content. Each header is defined by a key and value, letting you configure caching behavior, add security hardening directives, or include diagnostic markers.

request_headers — a list of headers that the CDN forwards to the origin when requesting the original object. Each header is defined by a key and value, making it possible to pass routing hints, A/B testing parameters, or other operational metadata required by backend systems.

The main parameter for creating a bucket is its name.
To validate a bucket name provided by the client, use the API method.

Managing S3 Buckets​

CDN service management for buckets is performed via s3_bucket objects.

Available management actions for each bucket:

  • Activate CDN service (enable the s3_bucket)
  • Deactivate CDN service (disable the s3_bucket)
  • Clear the bucket’s cache (delete previously cached objects from CDN servers)

S3 Bucket Statuses​

The status of an S3 bucket indicates its current state.

Possible statuses:

  • OK – CDN is enabled for the bucket
  • DISABLED – CDN is disabled for the bucket
  • BLOCKED – The bucket is blocked
note

Immediately after creation, the bucket status becomes OK.

Access Restrictions​

S3 buckets and resources support access restriction functionality, defined via the s3_resource.access_params and s3_bucket.access_params objects.
Structure of the access_params object:

{
    "disallowed_country_codes": [
        "RU",
        "BY"
    ]
}

The disallowed_country_codes field lists country codes from which requests will be rejected with a 403 Forbidden response.
Country codes must follow the two-letter format according to
ISO 3166 Alpha-2.

Signed URLs​

The fields signed_url_enabled and signed_url_key of s3_bucket objects control enabling and disabling the access restriction feature to buckets via signed URLs. This feature can be toggled by updating the s3_bucket object. When enabled, access to the bucket is granted only to holders of the corresponding signed URLs. The client is responsible for generating these signed URLs.

Below are recommendations for managing S3 objects.

Initial Setup:​

  1. Retrieve the list of available S3 providers from Arviol and share it with the client.
  2. Receive from the client the selected provider, provider URL, and S3 bucket name.
  3. Validate the provider URL and bucket name based on the selected provider.
  4. Create the S3 resource.
  5. Create the S3 bucket.
  6. Provide the client with the final CDN-accessible URL to bucket objects: s3_resource.cdn_s3_domain/s3_bucket.name

API Methods​

S3 Providers​

Provider Parameter Validation​

S3 Resources​

S3 Buckets​