AWS EmulatorをNode.jsのSDKから使う方法

​​AWS Emulator​Amazon S3,AWS SDK for JavaScript,Node.js,TypeScript

AWS SDK for JavaScript v3 は、AWS CLI と同じ環境変数で AWS Emulator に向けられます。ただし、エミュレーターの証明書だけは AWS_CA_BUNDLE では読まれないので、Node.js の NODE_EXTRA_CA_CERTS を1つ足します。S3 などを使う Node.js のコードを、AWS のアカウントなしでローカル環境や CI でテストしたいときの手順です。そのほか、SDK for JavaScript で別の設定が必要になるところ(localhost での S3、ホスト名の前に付く data-)も、検証環境で実行した出力のまま載せます。

補足

検証環境は Ubuntu 24.04(x86_64)、Node.js 22.23.4、AWS SDK for JavaScript v3(@aws-sdk/client-s3 などは 3.1169.0)、AWS Emulator 1.0.385(2026年11月14日リリース)です。AWS のアカウントと認証情報は使っていません。本物の AWS での動きは確かめておらず、記事で触れるところは公式ドキュメントを出どころにしています。ブラウザで動かす SDK、Docker で動かすエミュレーター、Jest や Vitest からの呼び出しは試していません。

AWS CLI と同じ環境変数に、NODE_EXTRA_CA_CERTS を足す

エミュレーターの入れ方は公式の Linux 向けの手順のとおりで、aws-emulator -t off で起動します(-t off はテレメトリーを切る指定)。SDK は npm で入れます。この記事では S3、STS、Cloud Map(client-servicediscovery)のクライアントと、認証情報を読む credential-providers を使います。

bash
npm install @aws-sdk/client-s3 @aws-sdk/client-sts @aws-sdk/client-servicediscovery @aws-sdk/credential-providers
npm pkg set type=module

コードは TypeScript で書き、Node.js でそのまま実行しています。Node.js 22.18.0 から、型の注釈を取り除いて .ts を実行する機能が既定で有効になりました(型チェックはしません)。import で書くために、package.json に "type": "module" を入れています。

エミュレーターを動かしたまま別の端末を開き、公式ドキュメントにある環境変数を設定します。最後の NODE_EXTRA_CA_CERTS が、Node.js のために足す1行です。

bash
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
export NODE_EXTRA_CA_CERTS=~/.aws/emulator/9297/ca.pem

SDK for JavaScript v3 は、接続先を決める AWS_ENDPOINT_URL に対応している SDKの1つです。接続先、認証情報、リージョンは、この環境変数から読まれました。読まれたものと、別の設定が必要だったものを図にまとめます。

SDK for JavaScript v3 で、接続先・認証情報・リージョンの環境変数は読まれた。AWS_CA_BUNDLE は読まれず NODE_EXTRA_CA_CERTS が必要。AWS_DISABLE_HOST_PREFIX_INJECTION は効かず disableHostPrefix: true が必要。localhost では S3 のバケット名がホスト名に入るので 127.0.0.1 のままにする
AWS CLI 用の環境変数のうち、SDK for JavaScript v3 で読まれたものと、別の設定が必要だったもの

証明書は AWS_CA_BUNDLE では読まれない

まず、STS の GetCallerIdentity で、どこに届いたかを確かめます。接続先も認証情報もコードには書きません。

ts
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";

// 接続先・認証情報・リージョンは環境変数から読ませる(コードには書かない)
const sts = new STSClient({});
const me = await sts.send(new GetCallerIdentityCommand({}));
console.log("Arn:", me.Arn);

NODE_EXTRA_CA_CERTS を設定する前に実行すると、AWS_CA_BUNDLE が設定してあっても、証明書のエラーで止まりました(スタックトレースは途中を省き、ホームディレクトリのパスは ~ に置き換えています)。

text
$ echo "AWS_CA_BUNDLE=$AWS_CA_BUNDLE"; node whoami.ts
AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
(省略)
Error: self-signed certificate
(省略)
  code: 'DEPTH_ZERO_SELF_SIGNED_CERT',

公式ドキュメントでは、AWS_CA_BUNDLE で証明書を読むのは AWS CLI、Boto3、SDK for Go とされていて、SDK for JavaScript v3 では、NODE_EXTRA_CA_CERTS に ca.pem のパスを設定するよう案内されています。設定して実行し直すと、エミュレーターに届きました。エミュレーターのアカウントIDは、0が12個並んだ決まった値です(出力では <12桁の0> に置き換えています)。

text
$ export NODE_EXTRA_CA_CERTS=~/.aws/emulator/9297/ca.pem
$ node whoami.ts
Arn: arn:aws:iam::<12桁の0>:user/emulator

Node.js のドキュメントによると、NODE_EXTRA_CA_CERTS は、Node.js がもともと信頼している証明書に ca.pem を足す設定です。もともとの証明書もそのまま使われます。読まれるのはプロセスを起動したときだけなので、コードの中で process.env に入れても効きません。エミュレーターは起動のたびに証明書を作り直しますが、パスを指しているだけなので、設定し直さずに使えます。

S3 にオブジェクトを書いて読む

S3 も、クライアントを new S3Client({}) で作るだけです。バケットを作り、文字列を書き込んで、一覧と中身を読みます。

ts
import {
  S3Client,
  CreateBucketCommand,
  PutObjectCommand,
  GetObjectCommand,
  ListObjectsV2Command,
} from "@aws-sdk/client-s3";

const s3 = new S3Client({});
const Bucket = "example-bucket";

await s3.send(new CreateBucketCommand({ Bucket }));
await s3.send(new PutObjectCommand({ Bucket, Key: "hello.txt", Body: "にゃー" }));

const list = await s3.send(new ListObjectsV2Command({ Bucket }));
console.log("Keys:", list.Contents?.map((o) => o.Key));

const obj = await s3.send(new GetObjectCommand({ Bucket, Key: "hello.txt" }));
console.log("hello.txt:", await obj.Body?.transformToString());
text
$ node s3.ts
Keys: [ 'hello.txt' ]
hello.txt: にゃー

接続先を localhost にすると、S3 だけ届かない

AWS_ENDPOINT_URL を https://localhost:9297 に変えて同じコードを実行すると、example-bucket.localhost というホスト名が見つからないというエラーになりました。バケット名がホスト名の前に付いています。

text
$ AWS_ENDPOINT_URL=https://localhost:9297 node s3.ts
(省略)
Error: getaddrinfo ENOTFOUND example-bucket.localhost

S3 には、バケット名を URL のパスに入れる書き方(パス形式)と、ホスト名に入れる書き方(仮想ホスト形式)があります。エミュレーターの公式ドキュメントによると、接続先が IP アドレスなら SDK はパス形式で送りますが、localhost にすると SDK for JavaScript は既定でホスト名に入れます。エミュレーターはホスト名に入った形を受け付けないので、AWS_ENDPOINT_URL は 127.0.0.1 のままにするよう書かれています。

どうしても localhost を使うなら、S3 のクライアントに forcePathStyle: true を渡すと、パス形式で送られて届きました。s3-path-style.ts は、s3.ts のクライアントをこの1行に変え、バケット名を example-bucket-2 にしたものです。証明書は localhost の名前でも発行されているので、証明書のエラーにはなりません。

ts
const s3 = new S3Client({ forcePathStyle: true });
text
$ AWS_ENDPOINT_URL=https://localhost:9297 node s3-path-style.ts
Keys: [ 'hello.txt' ]
hello.txt: にゃー
$ openssl x509 -in ~/.aws/emulator/9297/ca.pem -noout -ext subjectAltName
X509v3 Subject Alternative Name: 
    DNS:localhost, IP Address:127.0.0.1, IP Address:0:0:0:0:0:0:0:1

data- が付く API には disableHostPrefix: true を渡す

API の中には、SDK がホスト名の前に文字を付けて送るものがあります。公式ドキュメントでは、Cloud Map の DiscoverInstances の data-、Step Functions の StartSyncExecution の sync- などが挙げられています。AWS CLI と Boto3 は AWS_DISABLE_HOST_PREFIX_INJECTION で止められますが、SDK for JavaScript v3 では、クライアントを作るときに disableHostPrefix: true を渡すよう案内されています。

Cloud Map で名前空間とサービスを作り、インスタンスを1つ登録してから DiscoverInstances を呼ぶスクリプトで確かめました(作る部分は省いています)。引数に on を渡したときだけ disableHostPrefix: true にします。

ts
const disableHostPrefix = process.argv[2] === "on";
const sd = new ServiceDiscoveryClient({ disableHostPrefix });

AWS_DISABLE_HOST_PREFIX_INJECTION=true を設定したシェルでも、disableHostPrefix を渡さないと、data-127.0.0.1 に送ろうとして失敗しました。渡すと、登録したインスタンスが返りました。

text
$ echo "AWS_DISABLE_HOST_PREFIX_INJECTION=$AWS_DISABLE_HOST_PREFIX_INJECTION"; node discover.ts
AWS_DISABLE_HOST_PREFIX_INJECTION=true
disableHostPrefix: false -> Error getaddrinfo ENOTFOUND data-127.0.0.1
$ node discover.ts on
disableHostPrefix: true -> [ { AWS_INSTANCE_IPV4: '192.0.2.10' } ]

公式ドキュメントには、AWS_DISABLE_HOST_PREFIX_INJECTION を設定すると本物の AWS ではこうした操作が失敗するので、エミュレーターを使うシェルだけで設定するよう書かれています。

アクセスキーの環境変数が残っていると、エミュレーターに断られる

公式ドキュメントによると、AWS_ACCESS_KEY_ID などの環境変数は認証情報ファイルより優先されます。最初の unset をせずに残していると、SDK はその値で署名し、エミュレーターはリクエストを断ります。でたらめな値を入れて実行すると、エミュレーターが InvalidClientTokenId(HTTP 403)を返しました(出力は要点だけ残しています)。

text
$ AWS_ACCESS_KEY_ID=not-a-real-key AWS_SECRET_ACCESS_KEY=not-a-real-secret node whoami.ts
InvalidClientTokenId: The security token included in the request is invalid.
  '$fault': 'client',
  '$metadata': {
    httpStatusCode: 403,
(省略)

環境変数を使わず、コードで指定する

NODE_EXTRA_CA_CERTS はプロセスの起動前に決めておく必要があります。テストのコードの中だけで完結させたいときは、接続先、リージョン、認証情報、証明書をクライアントに直接渡せます。コードで渡した接続先は、環境変数の AWS_ENDPOINT_URL より優先されます。requestHandler に httpsAgent の設定をそのまま書く形は、SDK のバージョン 3.521.0 から使える短い書き方です。

ts
import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
import { fromIni } from "@aws-sdk/credential-providers";

// エミュレーターが起動のたびに書き出すファイルの場所(ポート 9297 のとき)
const dir = join(homedir(), ".aws", "emulator", "9297");

const s3 = new S3Client({
  endpoint: "https://127.0.0.1:9297",
  region: "us-east-1",
  credentials: fromIni({ filepath: join(dir, "emulator_credentials") }),
  requestHandler: {
    httpsAgent: { ca: readFileSync(join(dir, "ca.pem")) },
  },
});

const out = await s3.send(new ListBucketsCommand({}));
console.log("Buckets:", out.Buckets?.map((b) => b.Name));

env -i で PATH と HOME 以外の環境変数を消して実行しても、エミュレーターに届き、ここまでに作ったバケットが見えました。

text
$ env -i PATH="$PATH" HOME="$HOME" node explicit.ts
Buckets: [ 'example-bucket', 'example-bucket-2' ]

Node.js のドキュメントによると、ca を渡すと、もともと信頼している証明書は使われなくなります。このクライアントがつながるのはエミュレーターだけになるので、本物の AWS 向けのクライアントとは分けて作ります。

node:test のテストから使う

Node.js に組み込みの node:test で、S3 を使うテストを書いてみます。before で、接続先がエミュレーターかを最初に確かめます。

ts
import { test, before } from "node:test";
import assert from "node:assert/strict";
import {
  S3Client,
  CreateBucketCommand,
  PutObjectCommand,
  GetObjectCommand,
} from "@aws-sdk/client-s3";

const s3 = new S3Client({});
const Bucket = "test-bucket";

before(async () => {
  // 接続先がエミュレーターでなければ、ここで失敗させる
  assert.equal(process.env.AWS_ENDPOINT_URL, "https://127.0.0.1:9297");
  await s3.send(new CreateBucketCommand({ Bucket }));
});

test("書いたオブジェクトを、そのまま読み出せる", async () => {
  await s3.send(new PutObjectCommand({ Bucket, Key: "a.json", Body: JSON.stringify({ n: 1 }) }));
  const obj = await s3.send(new GetObjectCommand({ Bucket, Key: "a.json" }));
  assert.deepEqual(JSON.parse(await obj.Body!.transformToString()), { n: 1 });
});

test("ないキーを読むと NoSuchKey になる", async () => {
  await assert.rejects(
    s3.send(new GetObjectCommand({ Bucket, Key: "missing.json" })),
    { name: "NoSuchKey" },
  );
});

環境変数を設定したシェルで実行すると、2つとも通りました(出力は一部を省いています)。

text
$ node --test s3.test.ts
ok 1 - 書いたオブジェクトを、そのまま読み出せる
ok 2 - ないキーを読むと NoSuchKey になる
1..2
# tests 2
# pass 2
# fail 0

AWS_ENDPOINT_URL を外して実行すると、before の assert.equal で失敗し、2つのテストはどちらも失敗になりました(AssertionError などの行だけを抜き出しています)。

text
$ env -u AWS_ENDPOINT_URL node --test s3.test.ts
not ok 1 - 書いたオブジェクトを、そのまま読み出せる
    + actual - expected
  name: 'AssertionError'
  expected: 'https://127.0.0.1:9297'
not ok 2 - ないキーを読むと NoSuchKey になる
    + actual - expected
  name: 'AssertionError'
  expected: 'https://127.0.0.1:9297'
# pass 0
# fail 2
注意

公式ドキュメントによると、テストを動かすシェルに AWS_ENDPOINT_URL がないと、コードは見つかった認証情報で本物の AWS を呼びます。環境変数はテストを動かすスクリプトの中で設定し、テストのジョブの環境に本物の認証情報を置かないよう案内されています。

​Posted by 86