キャッシュサービスを利用する
PFCP が提供するキャッシュサービスについて説明します。
Note
本サービスは、SR1 を除く全拠点で利用可能です。 ただし、専有ノードを用いて構成されるため、専有ノードを契約していない組織では利用できません。
キャッシュサービスとは
キャッシュサービスは、データセットなど頻繁に読み込むデータへのアクセスを高速化するためのサービスです。
主に以下の特徴があります。
- 複数の Pod による同一キャッシュデータの利用
- HTTP(
PUT、GETなど)によるシンプルな読み書きインタフェース - Kubernetes の Namespace に基づく認証および認可
- バケットごとのクオータによる容量制限
キャッシュデータは Kubernetes の Namespace に対応する「バケット」と呼ばれる単位で管理されます。 バケットは同名の Namespace の Pod からのみ読み書きできます。 また、バケットごとにクオータ(容量の上限)が設定され、特定のバケットによる容量の使いすぎを防ぎます。
Warning
本サービスは永続ストレージではなく、データの永続性は保証されません。 また、通信路およびストレージへの保存のいずれにおいても暗号化を行っていません。 詳細は利用上の注意を確認の上、ご利用ください。
クオータによる容量管理
バケットごとに保持できるキャッシュデータの総容量は、クオータで管理されます。容量管理のアルゴリズムには Least Recently Used(LRU)を利用しており、最近利用されたキャッシュデータが優先的に保持されます。
アップロードによってバケットのクオータを超える場合は、最後に利用された時刻が古い順にキャッシュデータを削除して、必要な容量を確保します。
単一のキャッシュデータがクオータより大きい場合は、エラー(413 Payload Too Large)となります。
バケットごとのクオータのデフォルト値は 100 GiB です。 ただし、専有ノードの台数やバケット数、キャッシュデータのサイズ次第では、使用量がクオータ未満でも LRU でキャッシュデータを削除する場合もあります。 キャッシュデータを細かい単位(数 MiB〜数十 MiB 程度)に分けて作成すると、クオータを有効活用できます。
Note
ワークロードによっては「スラッシング」が生じる可能性があります。スラッシングとは、キャッシュしたデータが再利用される前に LRU によって削除され、キャッシュミス、書き込み、削除が繰り返される状態です。この状態ではヒット率が低下し、キャッシュの効果が十分に得られません。特に、クオータを超える量のデータを順番に繰り返し読み込むワークロードでは、LRU の性質上ヒット率がほぼ 0% になることがあります。スラッシングを避けるためには、ワークロードに見合ったクオータを確保することが重要です。クオータの変更を希望する場合は、サポート窓口までご連絡ください。
使い方
Namespace ごとに専用のバケットを提供しています。たとえば、Namespace org-<組織名>--foo からは同名のバケット org-<組織名>--foo を利用できますが、他の Namespace からはこのバケットを読み書きできません。
以下に、バケット org-<組織名>--foo へのアクセス可否を示します。
| ユーザの Namespace | バケット org-<組織名>--foo へのアクセス |
|---|---|
org-<組織名>--foo | ○ |
org-<組織名>--bar | × |
org-<組織名>(ルートネームスペース) | × |
バケットへのアクセスは、Bound Service Account Token を用いて認証および認可します。
Pod にラベル scs.preferred.jp/inject-config: "" を付与すると、Bearer トークンが /scs-secret/token に自動的にマウントされます。
kind: Pod
metadata:
labels:
scs.preferred.jp/inject-config: ""
Deployment や StatefulSet を利用する場合は、spec.template.metadata.labels にラベルを追加します。
kind: Deployment
spec:
template:
metadata:
labels:
scs.preferred.jp/inject-config: ""
Note
トークンには 3600 秒の有効期限が設定されており、定期的に更新されます。リクエストのたびに最新のトークンを読み込み、HTTP ヘッダ
Authorization: Bearer <トークン>として付与する必要があります。 後述する PFIO には最新のトークンを自動的に読み込む仕組みが実装されているため、追加の操作は必要ありません。
v1 API
v1 API のエンドポイントは以下のとおりです。
http://scs.scs-system.svc.cluster.local/v1/objects/<バケット名>/<キャッシュデータ名>
たとえば、Namespace org-<組織名>--foo からキャッシュデータ cache-foo を操作する場合は、以下の URL にアクセスします。
http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/cache-foo
以下の HTTP メソッドをサポートしています。
| HTTP メソッド | 操作内容 |
|---|---|
PUT | キャッシュデータのアップロード |
PATCH | scs-metadata の更新 |
GET | キャッシュデータのダウンロード |
HEAD | キャッシュデータのサイズおよび scs-metadata の取得 |
DELETE | キャッシュデータの削除 |
キャッシュデータごとに、HTTP ヘッダ scs-metadata で任意のメタデータ(最大 4096 バイト)を保持できます。更新時刻や ID を scs-metadata に埋め込むことで、キャッシュデータが更新されたかどうかを確認できます。
Note
PUTメソッドでは、キャッシュデータのサイズをContent-Lengthヘッダで指定する必要があります。 また、Transfer-Encoding: chunkedは利用できません。
キャッシュデータのアップロード・scs-metadata の更新
キャッシュデータのアップロードには PUT メソッドを利用します。scs-metadata は、PUT または PATCH メソッドで設定できます。
$ echo "TEST" > test.txt
$ curl -H "Authorization: Bearer $(cat /scs-secret/token)" -X PUT http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/test --data-binary @test.txt
$ curl -H "Authorization: Bearer $(cat /scs-secret/token)" -X PATCH http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/test -H "scs-metadata: baz"
キャッシュデータの確認・ダウンロード
キャッシュデータのサイズなどのメタデータを確認するには、HEAD メソッドを利用します。
$ curl -H "Authorization: Bearer $(cat /scs-secret/token)" -I http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/test
HTTP/1.1 200 OK
content-length: 5
content-type: application/octet-stream
scs-metadata: baz
...
content-length: 5 からキャッシュデータのサイズが 5 バイトであること、scs-metadata に PATCH で更新した baz が設定されていることがわかります。
キャッシュデータをダウンロードするには、GET メソッドを利用します。
$ curl -H "Authorization: Bearer $(cat /scs-secret/token)" http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/test
TEST
キャッシュデータの削除
キャッシュデータを削除するには、DELETE メソッドを利用します。クオータを超えた場合は LRU によってキャッシュデータが自動的に削除されますが、明示的にも削除できます。
$ curl -H "Authorization: Bearer $(cat /scs-secret/token)" -X DELETE http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/test
$ curl -H "Authorization: Bearer $(cat /scs-secret/token)" -I http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/test
HTTP/1.1 404 Not Found
...
Grafana ダッシュボードでの利用状況の確認
Grafana ダッシュボード の「PFCP > Cache Service Usage」で、組織全体のバケットの利用状況(キャッシュデータの総数、総容量、キャッシュヒット率など)を確認できます。
利用例
以下に利用例を示します。
PFIO を用いた S3 互換ストレージからのオブジェクト読み込み高速化
PFIO の HTTPCachedFS を利用すると、キャッシュサービスを透過的に利用し、Amazon S3 互換のオブジェクトストレージ(以下、S3 互換ストレージ)からのデータの読み込みを高速化できます。
キャッシュデータが存在しない場合、PFIO は元のストレージからデータを読み込み、自動的にキャッシュを行います。そのため、2 回目以降は高速に読み込めます。キャッシュデータは複数の Pod 間で共有できるため、固定されたデータセットを Job などで処理する場合に大きな効果が期待できます。
#!/usr/bin/env python3
import os
import time
import uuid
import pfio.v2 as pfio_v2
endpoint = os.environ["AWS_ENDPOINT_URL"]
bucket = os.environ["S3_BUCKET"]
access_key = os.environ["AWS_ACCESS_KEY_ID"]
secret_key = os.environ["AWS_SECRET_ACCESS_KEY"]
underlay = pfio_v2.from_url(
"s3://{}".format(bucket),
endpoint=endpoint,
aws_access_key_id=access_key,
aws_secret_access_key=secret_key,
create_bucket=True
)
cache_url = "http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo"
token_path = "/scs-secret/token"
# オブジェクトを更新した場合は、キャッシュデータの再作成が必要です。
# この例では、環境変数として DATASET_VERSION を設定し、
# データセットの更新時にキャッシュデータも再作成するようにしています。
# DATASET_VERSION が未設定の場合はランダムな値を使用するため、
# 実行ごとに新しいキャッシュデータが作成されます。
dataset_version = os.environ.get("DATASET_VERSION") or uuid.uuid4().hex
fs = pfio_v2.HTTPCachedFS(
cache_url + "/cache-{}-{}".format(bucket, dataset_version), underlay,
max_cache_size=10 * 1024 * 1024 * 1024, # max 10 GiB cache
bearer_token_path=token_path
)
key = "hello.txt"
payload = os.urandom(256 * 1024) # 256 KiB
with fs.open(key, "wb") as f:
f.write(payload)
read_times = []
for i in range(3):
t0 = time.perf_counter()
with fs.open(key, "rb") as f:
data = f.read()
read_times.append(time.perf_counter() - t0)
assert data == payload
print(f"read {i + 1}: {read_times[-1] * 1000:.1f} ms")
print(f"average read time: {sum(read_times) / len(read_times) * 1000:.1f} ms")
1 回目の読み込みは、S3 互換ストレージからオブジェクトを取得してキャッシュサービスに保存するため時間がかかりますが、2 回目以降は大幅に短縮されます。
$ python3 s3_example.py
read 1: 50.4 ms
read 2: 2.9 ms
read 3: 1.8 ms
average read time: 18.4 ms
データセットのサイズがクオータを上回る場合、前述のスラッシングにより性能は改善しないこともあります。この場合は、データセットの分割や、クオータの変更を検討してください。
Tip
Range GET も利用できますが、読み込み性能は低下します。
ccache と連携したビルド高速化
CI/CD において ccache の http-storage 機能とキャッシュサービスを連携すると、ビルドキャッシュを有効活用できます。複数の Pod 間でビルドキャッシュを共有できるため、GitHub Actions で PR ごとにビルドを行うといった用途で効果が期待できます。
$ ccache --version
ccache version 4.9.1
Features: file-storage http-storage redis+unix-storage redis-storage
...
$ export CCACHE_MAXSIZE=10G
$ export CCACHE_REMOTE_ONLY=true
$ export CCACHE_REMOTE_STORAGE="http://scs.scs-system.svc.cluster.local/v1/objects/org-<組織名>--foo/ccache|bearer-token=$(cat /scs-secret/token)"
$ ccache -s
Local storage:
Cache size (GB): 0.0 / 10.0 ( 0.00%)
$ gcc -c hello.c
$ ccache -s
Cacheable calls: 1 / 1 (100.0%)
Hits: 0 / 1 ( 0.00%)
Direct: 0
Preprocessed: 0
Misses: 1 / 1 (100.0%)
Local storage:
Cache size (GB): 0.0 / 10.0 ( 0.00%)
Remote storage:
Hits: 0 / 1 ( 0.00%)
Misses: 1 / 1 (100.0%)
$ gcc -c hello.c
$ ccache -s
Cacheable calls: 2 / 2 (100.0%)
Hits: 1 / 2 (50.00%)
Direct: 1 / 1 (100.0%)
Preprocessed: 0 / 1 ( 0.00%)
Misses: 1 / 2 (50.00%)
Local storage:
Cache size (GB): 0.0 / 10.0 ( 0.00%)
Remote storage:
Hits: 1 / 2 (50.00%)
Misses: 1 / 2 (50.00%)
Note
上記の例では
ccacheにトークンを直接設定しているため、トークンの有効期限(3600 秒)を超えるビルドには利用できません。その場合は、Authorizationヘッダを挿入するプロキシを別途導入する必要があります。
利用上の注意
永続ストレージとの違い
Warning
本サービスは永続ストレージではありません。そのため、以下の制約があります。
- データの永続性は保証されません。
- 障害発生の前後にキャッシュデータを更新した場合、古いキャッシュデータが読み込まれる可能性があります。
実際の利用においては、キャッシュデータが消えた場合に再度アップロードする仕組みや、更新したキャッシュデータに新たな一意の名前を付与する仕組みをあわせて実装することを推奨します。
キャッシュデータは、契約している専有ノードのローカルストレージ上に保持されます。 そのため、専有ノードの解約や交換、ローカルストレージの故障が発生した場合、キャッシュデータは失われます。
データ暗号化について
Warning
通信路およびストレージへの保存のいずれにおいても暗号化を行っていません。法令などにより暗号化が必要な場合は、クライアント側で暗号化してください。
メンテナンス
キャッシュサービスは、契約している専有ノードを用いて構成されます。そのため、メンテナンス時には以下の影響があります。
- キャッシュデータは削除されることがあります。
- ノードの停止を伴うメンテナンスでは、利用可能な容量は一時的に減少することがあります。
- 契約ノードが 1 台の場合、一時的にキャッシュサービスを利用できなくなります。