developersIO
CloudFront Functions の URI 書き換えルールを KeyValueStore で管理してみた

CloudFront Functions の URI 書き換えルールを KeyValueStore で管理してみた

CloudFront KeyValueStore を使用して、URI 書き換えルールを Function のコードから分離し、コード再発行なしでルール更新を実現する方法を紹介します。前回の S3 URL 書き換え実装を、より柔軟に運用可能な構成へ改善してみました。
AWSAmazon CloudFrontAmazon S3CloudFront FunctionsCloudFront KeyValueStore
2026.08.04

はじめに

テクニカルサポートの 片方 です。
前回執筆したブログでは、CloudFront Functions を使用して、/about へのリクエストを CloudFront 内部で /about/index.html に書き換え、Amazon S3 に配置した HTML ファイルを配信する方法を紹介しました。
なお、この処理は HTTP リダイレクトではないため、ブラウザのアドレスバーは /about のままです。

https://dev.classmethod.jp/articles/cloudfront-functions-s3-url-rewrite-handson/

前回の実装では、書き換え先の URI を CloudFront Function のコードに直接記述していました。そのため、書き換え先を変更する場合は、Function のコード修正、テスト、発行が必要になります。

今回は、CloudFront KeyValueStore（KVS）を使用して、URI の書き換えルールを Function のコードから分離します。CloudFront Function は KVS から書き換え先を取得するだけの汎用的な処理とし、書き換え先は KVS のキー・バリューで管理します。CloudFront KeyValueStore は CloudFront Functions から参照できる Key-Value ストアであり、コードとは独立して参照データを更新できます。

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/kvs-with-functions.html

本ブログでは、前回作成した S3 バケットおよび CloudFront ディストリビューションを利用し、/about に対する書き換え先を以下のように切り替えます。

変更前
/about → /about/index.html

変更後
/about → /about-v2/index.html

書き換え先の変更後も、利用者がアクセスする URL は /about のままです。CloudFront Function のコードは変更せず、KVS の値だけを更新して、S3 から取得するオブジェクトを切り替えてみます。

検証内容

前回の記事では、CloudFront Function のコードに書き換え先を直接記述し、/about へのリクエストを /about/index.html へ書き換えました。

今回は、書き換え先を CloudFront KeyValueStore（KVS）で管理します。CloudFront Function は KVS を参照し、取得した値をもとに URI を書き換えます。

前回記事との差分

項目 前回 今回
書き換え先の管理 Function のコード CloudFront KeyValueStore
書き換え先の変更 Function の修正・発行が必要 KVS の値を更新
Function の役割 固定の URI を書き換える KVS を参照して URI を書き換える

CloudFront Function は、Viewer request イベントで KVS を参照し、S3 オリジンへ送信する URI を書き換えます。
今回の処理は HTTP リダイレクトではありません。そのため、ブラウザのアドレスバーは /about のままです。

ブラウザ
  |
  | GET /about
  v
CloudFront Function
  |
  | KVS から書き換え先を取得
  v
Amazon S3

今回の書き換えルール

初期状態では、以下のルールを KVS に登録します。

Key:   rewrite:/about
Value: /about/index.html

/about へアクセスすると、CloudFront 内部で /about/index.html に書き換えられます。
次に、KVS の値だけを以下のように更新します。

Key:   rewrite:/about
Value: /about-v2/index.html

更新後もアクセス URL は /about のままですが、S3 から取得するオブジェクトは about-v2/index.html に切り替わります。

変更前: /about → /about/index.html
変更後: /about → /about-v2/index.html

実装してみた

S3 に切り替え先のオブジェクトを追加する

前回作成した S3 バケットに、書き換え先を切り替えるための about-v2/index.html を追加します。
追加後のオブジェクト構成は以下のとおりです。

<バケット名>/
├── index.html
├── about/
│   └── index.html
└── about-v2/
    └── index.html

about-v2/index.html には、切り替え後であることが分かる内容を記載します。

about-v2/index.html
<!doctype html>
<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <title>About v2</title>
  </head>
  <body>
    <h1>About ページ v2</h1>
    <p>CloudFront KeyValueStore の設定を変更して配信しています。</p>
    <p><a href="/">トップページへ戻る</a></p>
  </body>
</html>

S3 コンソールから、前回使用したバケットを開き、about-v2 フォルダを作成します。続けて、作成したフォルダへ index.html をアップロードします。

01

以降の手順では、CloudFront KeyValueStore の値を変更して、/about へのリクエストに対する書き換え先を以下のように切り替えます。
S3 のオブジェクトはキーで識別されるため、本記事では about-v2/index.html を追加し、既存の about/index.html とは別のオブジェクトとして用意します。既存ファイルを上書きせず、書き換え先を変更することで切り替え結果を確認しやすくしています。

変更前: /about → /about/index.html
変更後: /about → /about-v2/index.html

CloudFront KeyValueStore を作成する

続いて、URI の書き換え先を管理する CloudFront KeyValueStore（KVS）を作成します。
CloudFront コンソールで Functions を開き、KeyValueStores タブから Create KeyValueStore を選択します。
以下の値を入力して作成します。

項目 値
Name rewrite-rules-kvs
Description URI rewrite rules for CloudFront Functions
S3 URI 未入力

今回はキー・バリューをコンソールから手動で登録するため、S3 URI は未入力のままにします。
なお、S3 上のファイルを指定してキー・バリューをインポートすることもできますが、インポートできるのは KVS の作成時のみです。

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/kvs-with-functions-create.html?utm_source=openai

02
03

KVS を作成後、詳細画面の Key value pairs から Add key value pairs を選択し、以下のキー・バリューを登録します。

Key:   rewrite:/about
Value: /about/index.html

04
05

今回の Function では、リクエスト URI をもとに rewrite:/about のようなキーを検索します。

リクエスト URI: /about
KVS のキー:      rewrite:/about
書き換え先:       /about/index.html

キーに rewrite: というプレフィックスを付けることで、書き換えルールであることを明確にしています。後から別用途の設定を追加する場合も、キーの用途を判別しやすくなります。
この時点では、以下の書き換えルールを登録した状態です。

  • /about → /about/index.html

次のセクションでは、この KVS を参照するように CloudFront Function のコードを変更します。
CloudFront KeyValueStore は CloudFront Functions から参照できる Key-Value ストアです。Function から利用するには、後続の手順で KVS を Function に関連付け、JavaScript runtime cloudfront-js-2.0 を使用します。

CloudFront Function を KVS 参照のコードへ変更する

前回は、/about の書き換え先を CloudFront Function のコードに直接記述していました。

if (request.uri === '/about') {
    request.uri = '/about/index.html';
}

今回は、CloudFront KeyValueStore（KVS）から書き換え先を取得するように変更します。
CloudFront コンソールで前回作成した Function を開き、Build タブのコードを以下に置き換えます。

import cf from 'cloudfront';

const kvs = cf.kvs();

async function handler(event) {
    const request = event.request;

    // /about/ は /about として扱う
    const normalizedUri =
        request.uri.length > 1 && request.uri.endsWith('/')
            ? request.uri.slice(0, -1)
            : request.uri;

    try {
        const destination = await kvs.get(`rewrite:${normalizedUri}`);

        // 内部 URI 書き換えでは、絶対パスだけを許可する
        if (destination.startsWith('/') && !destination.startsWith('//')) {
            request.uri = destination;
        }
    } catch (error) {
        // KVS にキーがない場合は URI を変更しない
    }

    return request;
}

このコードでは、リクエスト URI をもとに rewrite:<URI> 形式のキーを KVS から取得します。

リクエスト URI KVS のキー 書き換え後の URI
/about rewrite:/about /about/index.html
/about/ rewrite:/about /about/index.html
/ rewrite:/ 変更なし

kvs.get() は、指定したキーが存在しない場合にエラーとなります。そのため、try...catch で例外を処理し、KVS にルールがない URI は変更せずにそのまま S3 オリジンへ送信します。

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/example_cloudfront_functions_kvs_key_value_pairs_section.html?utm_source=openai

また、KVS の値は / で始まる URI のみを許可しています。今回の用途は CloudFront 内部での URI 書き換えであるため、https://test-v1.com/ のような外部 URL や、//test-v1.com/ のようなスキーム相対 URL を書き換え先として使用しないようにしています。

この時点では KVS に以下の値を登録しているため、/about または /about/ へのアクセスは /about/index.html へ書き換えられます。

Key:   rewrite:/about
Value: /about/index.html

KVS を使用する Function では、JavaScript runtime cloudfront-js-2.0 を指定する必要があります。次のセクションで、作成した KVS を Function に関連付けて発行します。

KVS を CloudFront Function に関連付けて発行する

作成した KVS を、CloudFront Function に関連付けます。
KVS の詳細画面下部にある Associated functions セクションで、Go to functions を選択します。

06

Functions 一覧から、前回作成した CloudFront Function を選択します。
Function の詳細画面で、Associate KeyValueStore セクションまでスクロールし、Associate existing KeyValueStore を選択します。
先ほど作成した rewrite-rules-kvs を選択し、Associate KeyValueStore を選択します。

07
08

KVS を関連付けると、Function 内の以下のコードから rewrite-rules-kvs を参照できるようになります。

const kvs = cf.kvs();

KVS の関連付けは保存不要で直ちに反映されます。ただし、今回のように Function のコードも変更しているため、関連付け後にテストしてから Function を発行します。CloudFront Function には 1 つの KVS だけを関連付けられます。
Test タブで、リクエスト URI に /about を指定してテストします。実行結果の uri が、以下のようになれば成功です。

/about/index.html

09
テスト後、発行タブで 関数を発行 を選択します。
今回のように Function のコードと KVS の関連付けを変更した場合、ディストリビューションで使用される LIVE ステージへ反映するために Function の発行が必要です。発行後、関連付け済みのキャッシュビヘイビアは、ディストリビューションのデプロイ完了後に新しい Function を使用します。

010
以降、同じ KVS 内のキー・バリューだけを更新する場合、Function の再関連付けや再発行は不要です。

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/kvs-with-functions-associate.html

確認してみた

初期状態で URI が書き換えられることを確認する

Function の発行後、CloudFront ディストリビューションのステータスが Deployed になったことを確認します。
初期状態では、KVS に以下の値を登録しています。

Key:   rewrite:/about
Value: /about/index.html

CloudFront のドメイン名に /about を付けてアクセスします。

https://<CloudFront ドメイン名>/about

about/index.html の内容が表示されました。

011

アドレスバーは /about のままです。HTTP リダイレクトではなく、CloudFront Function が S3 オリジンへ送信する URI を /about/index.html に書き換えていることを確認できました。

アクセス URL:        /about
書き換え後の URI:    /about/index.html
表示するオブジェクト: about/index.html

KVS の値だけを更新して配信先を切り替える

次に、Function のコードを変更・発行せずに、KVS の値だけを更新します。
KVS の詳細画面を開き、Key value pairs セクションの Edit を選択します。
rewrite:/about の値を、以下のように変更します。

## 変更前
Key:   rewrite:/about
Value: /about/index.html

## 変更後
Key:   rewrite:/about
Value: /about-v2/index.html

012

同じ URL に再度アクセスします。

https://<CloudFront ドメイン名>/about

013

今度は about-v2/index.html の内容が表示されました。
このときも、ブラウザのアドレスバーは /about のままです。
CloudFront Function のコード、KVS の関連付け、Function の発行はいずれも行っていません。KVS の値だけを更新して、URI の書き換え先を切り替えられました。成功ですね！

まとめ

CloudFront KeyValueStore を使用して、CloudFront Functions の URI 書き換えルールをコードから分離しました。
今回は、KVS の rewrite:/about の値を更新することで、CloudFront Function を再発行せずに書き換え先を切り替えられました。
CloudFront KeyValueStore は、今回のように CloudFront Functions で参照する小さな設定値を、コードとは別に管理したい場合に有効です。例えば、以下のような用途が考えられます。

  • URI 書き換え・リダイレクトの対応表
  • 国、ホスト名、パスに応じた配信先の切り替え
  • メンテナンス画面への切り替え
  • 機能フラグや A/B テストの設定

一方で、KVS は CloudFront Functions 実行中に値を書き込む用途や、大量データ・ユーザーごとの状態を管理する用途には向いていません。
書き換えルールの変更頻度が高い場合や、ルールを Function のコード変更と分けて運用したい場合に、CloudFront KeyValueStore を検討してみてください。
本ブログが誰かの参考になれば幸いです。

参考資料

クラスメソッドオペレーションズ株式会社について

クラスメソッドグループのオペレーション企業です。
運用・保守開発・サポート・情シス・バックオフィスの専門チームが、IT・AIをフル活用した「しくみ」を通じて、お客様の業務代行から課題解決や高付加価値サービスまでを提供するエキスパート集団です。
当社は様々な職種でメンバーを募集しています。
「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、クラスメソッドオペレーションズ株式会社 コーポレートサイト をぜひご覧ください。※2026年1月 アノテーション㈱から社名変更しました

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事

CloudFront Functions で S3 静的サイトの URL を書き換えてみた
片方 裕人
2026.08.04
CloudFront Functions を使ってリダイレクト処理をしてみた
すながわ
2025.10.12
S3静的ウェブサイトホスティングのリダイレクト設定はPOSTリクエストに対応しているの確認してみた
さいちゃん
2025.10.26
[CloudFront Functions] KeyValue ストアのチュートリアルを参考にリダイレクト処理をやってみた
すながわ
2025.10.19