環境変数とシークレット

アプリが外部サービスと連携するには、APIキーや接続情報が必要です。これらの値をコードに直接書くのではなく、環境変数として管理することで、安全かつ柔軟に設定を切り替えられます。

このページでは、Keelsonで環境変数とシークレットを設定・管理する方法を説明します。

環境変数の設定方法

Keelsonでは、環境変数を2つの方法で設定できます。

keelson.yaml の env フィールドに記述した値は、ビルド時と実行時の両方で利用できます。

slug: my-app
runtime: python-slim
command: "python app.py"
env:
  PORT: "8080"
  NODE_ENV: "production"

秘密にする必要のない設定値（ポート番号、動作モードなど）はここに書きます。

APIキーやアクセストークンなどの機密情報は、コンソールからシークレットとして設定します。シークレットは暗号化されてデータベースに保存され、実行時にアプリへ注入されます。

シークレットの値はコンソール上で再表示されません。キー名と最終更新日時のみ確認できます。

シークレットは、ワークスペース単位とアプリ単位の2つのスコープで設定できます。

コンソールの シークレット ページで設定します。ワークスペース内のすべてのアプリから参照できます。

複数のアプリで共通して使う値（共有APIキーなど）に適しています。

コンソールのアプリ詳細画面で設定します。そのアプリだけに適用されます。

特定のアプリだけ別の値を使いたい場合や、ワークスペースシークレットを上書きしたい場合に使います。

同じキー名の環境変数が複数の場所で設定されている場合、次の順で優先されます。

たとえば、ワークスペースシークレットに API_KEY を設定し、特定のアプリだけ別の API_KEY を使いたい場合は、そのアプリにアプリシークレットとして設定すれば上書きできます。

keelson.yaml の env も同様に、変更後は再デプロイで反映されます。

タイミング	keelson.yaml の `env`	シークレット
ビルド時	利用できる	利用できない
実行時	利用できる	利用できる

フロントエンドのビルドで環境変数が必要な場合（例: VITE_API_URL）は、keelson.yaml の env に記述してください。シークレットはビルドプロセスには渡されません。

シークレットと keelson.yaml の env は、どちらも通常の環境変数としてアプリから参照できます。

Python:

import os
api_key = os.environ["API_KEY"]

Node.js:

const apiKey = process.env.API_KEY;

Go:

apiKey := os.Getenv("API_KEY")

以下のような値は、keelson.yaml ではなくコンソールのシークレットとして設定してください。

Keelsonは、以下の環境変数を自動的にアプリに設定します。ユーザーが同じキー名で値を設定する必要はありません。