Skip to main content

caches

Creates, updates, deletes, gets or lists a caches resource.

Overview​

Namecaches
TypeResource
Idaws.storagegateway.caches

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
cache_allocated_in_bytesinteger (int64)The amount of cache in bytes allocated to a gateway.
cache_dirty_percentagenumber (double)The file share's contribution to the overall percentage of the gateway's cache that has not been persisted to Amazon Web Services. The sample is taken at the end of the reporting period.
cache_hit_percentagenumber (double)Percent of application read operations from the file shares that are served from cache. The sample is taken at the end of the reporting period.
cache_miss_percentagenumber (double)Percent of application read operations from the file shares that are not served from cache. The sample is taken at the end of the reporting period.
cache_used_percentagenumber (double)Percent use of the gateway's cache storage. This metric applies only to the gateway-cached volume setup. The sample is taken at the end of the reporting period.
disk_idsarrayAn array of strings that identify disks that are to be configured as working storage. Each string has a minimum length of 1 and maximum length of 300. You can get the disk IDs from the ListLocalDisks API.
gateway_arnstringThe Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_cacheselectregionReturns information about the cache of a gateway. This operation is only supported in the cached volume, tape, and file gateway types. The response includes disk IDs that are configured as cache, and it includes the amount of cache allocated and used.
add_cacheupdateregion, GatewayARN, DiskIdsConfigures one or more gateway local disks as cache for a gateway. This operation is only supported in the cached volume, tape, and file gateway type (see How Storage Gateway works (architecture). In the request, you specify the gateway Amazon Resource Name (ARN) to which you want to add cache, and one or more disk IDs that you want to configure as cache.
cancel_cache_reportexecregion, CacheReportARNCancels generation of a specified cache report. You can use this operation to manually cancel an IN-PROGRESS report for any reason. This action changes the report status from IN-PROGRESS to CANCELLED. You can only cancel in-progress reports. If the the report you attempt to cancel is in FAILED, ERROR, or COMPLETED state, the cancel operation returns an error.
start_cache_reportexecregion, FileShareARN, Role, LocationARN, BucketRegion, ClientTokenStarts generating a report of the file metadata currently cached by an S3 File Gateway for a specific file share. You can use this report to identify and resolve issues if you have files failing upload from your gateway to Amazon S3. The report is a CSV file containing a list of files which match the set of filter parameters you specify in the request. The Files Failing Upload flag is reset every 24 hours and during gateway reboot. If this report captures the files after the reset, but before they become flagged again, they will not be reported as Files Failing Upload. The following requirements must be met to successfully generate a cache report: You must have s3:PutObject and s3:AbortMultipartUpload permissions for the Amazon S3 bucket where you want to store the cache report. No other cache reports can currently be in-progress for the specified file share. There must be fewer than 10 existing cache reports for the specified file share. The gateway must be online and connected to Amazon Web Services. The root disk must have at least 20GB of free space when report generation starts. You must specify at least one value for InclusionFilters or ExclusionFilters in the request.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Returns information about the cache of a gateway. This operation is only supported in the cached volume, tape, and file gateway types. The response includes disk IDs that are configured as cache, and it includes the amount of cache allocated and used.

SELECT
cache_allocated_in_bytes,
cache_dirty_percentage,
cache_hit_percentage,
cache_miss_percentage,
cache_used_percentage,
disk_ids,
gateway_arn
FROM aws.storagegateway.caches
WHERE region = '{{ region }}' -- required
;

UPDATE examples​

Configures one or more gateway local disks as cache for a gateway. This operation is only supported in the cached volume, tape, and file gateway type (see How Storage Gateway works (architecture). In the request, you specify the gateway Amazon Resource Name (ARN) to which you want to add cache, and one or more disk IDs that you want to configure as cache.

UPDATE aws.storagegateway.caches
SET 
GatewayARN = '{{ GatewayARN }}',
DiskIds = '{{ DiskIds }}'
WHERE 
region = '{{ region }}' --required
AND GatewayARN = '{{ GatewayARN }}' --required
AND DiskIds = '{{ DiskIds }}' --required
RETURNING
gateway_arn;

Lifecycle Methods​

Cancels generation of a specified cache report. You can use this operation to manually cancel an IN-PROGRESS report for any reason. This action changes the report status from IN-PROGRESS to CANCELLED. You can only cancel in-progress reports. If the the report you attempt to cancel is in FAILED, ERROR, or COMPLETED state, the cancel operation returns an error.

EXEC aws.storagegateway.caches.cancel_cache_report 
@region='{{ region }}' --required 
@@json=
'{
"CacheReportARN": "{{ CacheReportARN }}"
}'
;
Last updated on