S3アクション

S3アクションは、S3と、MinIO、Cloudflare R2、Versity GatewayのようなS3のプロトコルを話すストレージのオブジェクトを読み書きします。APIが保存したものを、ワークフローから確かめられます。

外部アクションとしてmozership/probe-s3 で公開しています。ワークフローが初めて使うときにProbeがダウンロードし、固定したコミットのaction.ymlが示すSHA-256と一致する実行ファイルだけを実行します。Probe v1.21.0以降が必要です。

基本的な構文

ワークフローでは40文字のコミットSHAでアクションを固定します。各リリース のノートの先頭に、コピーして使うアクションとコミットがあります。このページの例では、actionsで一度だけ名前を付けています。actionsにはProbe v1.24.0以降が必要です。それより前のProbeでは、各usesにアクションを完全な形で書きます。

name: Upload
actions:
  s3: github.com/mozership/probe-s3@8d2a120ffe6f2860229f5b6171a3477ed0f07b6d # v0.1.0
jobs:
  - name: upload
    steps:
      - name: Upload an avatar through the API
        id: upload
        uses: http
        with:
          url: https://api.example.com
          post: /avatars
          multipart:
            image:
              file: ./fixtures/logo.png
        test: res.code == 201
        outputs:
          key: res.body.key
 
      - name: The object is in the bucket, as it was sent
        uses: s3
        with:
          bucket: example-avatars
          region: ap-northeast-1
          head: "{{outputs.upload.key}}"
        test: res.code == 200 && res.content_type == "image/png" && res.metadata.owner == "42"

1つのステップは、1つのバケットに対して1つの操作をします。バケットの作成と削除はできません。

操作

ステップは次のキーのどれか1つで操作を指定します。書けるのは1つだけです。

パラメータ

これら以外のキーをwithに書くと、何も送らずにステップが失敗します。action.ymlがこれらをparamsとして宣言しているので、probe checkはそのようなキーを行番号つきで報告します。getにbodyを付けるように、操作が受け付けないパラメータを指定した場合も同じように失敗します。

path_styleのデフォルトは、endpointがあればtrueです。MinIOなどは1つの名前で提供されるためです。AWSではfalseですが、名前にドットを含むバケットは例外です。*.s3.<region>.amazonaws.comの証明書がその名前に対応しないためです。

listが返すのは1ページ分です。最大max_keys個のオブジェクトを返し、ストレージにまだ残りがあるかはres.truncatedで分かります。マルチパートアップロードには対応していません。

認証情報

withにaccess_key_id、secret_access_key、session_tokenのどれもなければ、アクションはProbeを実行している環境からAWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKENを読みます。どちらにも認証情報がなければ、公開バケットが受け付ける形で、リクエストを署名なしで送ります。アクションはプロファイルもインスタンスメタデータも、そのほかの認証情報の取得元も読まないので、ストレージ以外には接続しません。

できるだけ、認証情報は環境変数に任せてください。withに書いたシークレットアクセスキーは、結果にもレポートにも出ません。v1.24.0以降のProbeは、--verboseの出力とアクションのログでもsecret_access_keyとsession_tokenの値を伏せます。それより前のProbeでwithから渡すときは、その変数をsecretsに書いてください。

レスポンスオブジェクト

getとheadでは、ヘッダーが示すオブジェクトの情報が加わります。

getでは内容が加わります。

res.sha256とres.sizeは、オブジェクトがどれだけ大きくても全体についての値です。バイナリや大きなオブジェクトは、書き込んだステップのreq.sha256や既知のダイジェストとこれらを比べて確かめます。

putではres.etagが加わります。listでは次のものが加わります。

ストレージが応答した後は、その応答が結果になります。そのため、消えているはずのキーの404や、閉じているはずのバケットの403をテストで確かめられます。エラーとして失敗するのは、接続の拒否やタイムアウトのように、応答が得られなかったリクエストだけです。

例

AWSに対して、環境の認証情報を使う例です。

steps:
  - name: The export is there and not empty
    uses: s3
    with:
      bucket: example-exports
      region: ap-northeast-1
      list: "daily/{{vars.today}}/"
    test: "res.code == 200 && res.count > 0 && all(res.objects, #.size > 0)"

MinIOに対して、フィクスチャを書いて読み戻す例です。ジョブのdefaultsを、ワークフローがアクションに付けた名前をキーにして書くと、エンドポイント、バケット、認証情報を各ステップに書かずに済みます。

jobs:
  - name: fixtures
    defaults:
      s3:
        endpoint: http://localhost:9000
        bucket: fixtures
        access_key_id: "{{vars.minio_user}}"
        secret_access_key: "{{vars.minio_password}}"
    steps:
      - name: Put a fixture
        id: put
        uses: s3
        with:
          put: config/app.json
          body:
            enabled: true
        test: res.code == 200
        outputs:
          sha256: req.sha256
 
      - name: Get it
        uses: s3
        with:
          get: config/app.json
        test: res.body.enabled == true && res.sha256 == outputs.put.sha256
 
      - name: A key that must not be there
        uses: s3
        with:
          head: config/removed.json
        test: res.code == 404

リダイレクト

AWSでは、リクエストに署名したリージョンにないバケットを、AWSが応答で示したリージョンから読みます。ストレージが返したLocationも、ストレージの中にとどまる場合は5回まで追います。amazonaws.comの下、またはendpointのホストとその下の名前がこれにあたります。リクエストは行き先ごとに署名し直します。それ以外へのリダイレクトは追わず、そのまま結果になります。

ガードの下での動作

このアクションは実行のガードを守り、action.ymlでguard: [read-only, allow-host]を宣言しています。そのため、どちらの下でも--allow-actionなしで実行されます。アクションが拒否したステップは、種別refusedで失敗します。

• --read-onlyの下では、get、head、listだけを実行します。putとdeleteは、何も送らず、fileも読まないうちに拒否します。
• --allow-hostの下では、リクエストの送り先のホストがすべて、実行で許可されている必要があります。バケットを指定するホスト（AWSでは<bucket>.s3.<region>.amazonaws.com、path_styleではs3.<region>.amazonaws.com）と、各リダイレクト先のホストです。ポートのないURLは、スキームの既定のポート（httpは80、httpsは443）として扱います。--allow-host '*.amazonaws.com'とすれば、どのリージョンのバケットも許可されます。

ガードを参照してください。

関連項目

• 外部アクション - Probeが外部アクションを解決し、照合する仕組み
• HTTP - 通常のHTTPリクエスト
• Redis - RedisまたはValkeyのサーバーでのコマンド