secrets

Goldsky シークレット管理

パイプラインのシンク認証情報用のシークレットを作成、管理します。既存の認証情報をローテーションする場合は、シークレット名を維持したまま goldsky secret update を使用してください。 使用中のシークレットを削除して更新しないでください。認証情報のローテーションを参照してください。

エージェント向け手順

認証情報の安全な取り扱い： --value '...' を使って認証情報を直接渡すと、ユーザーのシェル履歴に記録され、コマンドの実行中はプロセス一覧にも表示されます。可能な限り、goldsky secret create では --value を省略し、CLI の対話形式のプロンプトで接続文字列を入力してください（機密情報が argv や履歴に触れることはありません）。--value の直接指定は非対話型のスクリプトに限り、公開したシークレット（goldsky secret reveal）を会話に貼り付けないでください。

このスキルが呼び出されたら、次の簡潔なワークフローに従ってください。

ステップ 1：ログインを確認し、既存のシークレットを一覧表示する

goldsky secret list を実行して、認証を確認し、既存のシークレットを表示します。

認証に失敗した場合： 先に auth-setup スキルを呼び出してください。

ステップ 2：意図をすばやく把握する

不要な質問は避けてください。 ユーザーの意図が文脈から明確な場合は、そのまま進めてください。

• ユーザーが「postgres のシークレットを作成して」と言った場合 → そのまま認証情報の確認に進みます
• ユーザーが接続文字列を貼り付けた場合 → すぐに解析します（接続文字列の解析を参照）
• ユーザーが特定のプロバイダー（Neon、Supabase など）に言及した場合 → プロバイダー固有のガイダンスを使用します

意図が本当に不明確な場合に限り、AskUserQuestion を使用してください。

ステップ 3：接続文字列の解析（PostgreSQL の場合に推奨）

ユーザーが接続文字列を提示した場合は、質問せずに直接解析してください。

PostgreSQL 接続文字列の形式：

postgres://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require
postgresql://USER:PASSWORD@HOST/DATABASE

解析の手順：

1. user、password、host、port（デフォルトは 5432）、databaseName を抽出します
2. JSON をすぐに構成します
3. 追加の質問をせずにシークレットを作成します

例 - ユーザーが提示する内容：

postgresql://neondb_owner:[email protected]/neondb?sslmode=require

接続文字列を直接使用して作成します：

goldsky secret create --name SUGGESTED_NAME
# When prompted, paste the connection string:
# postgresql://neondb_owner:[email protected]/neondb?sslmode=require

ステップ 4：プロバイダー固有の簡単な手順

データベースがまだありませんか？ Goldsky がホストする Postgres をプロビジョニングします（Scale プラン以上）：

ユーザーがまだ Postgres データベースを持っていない場合、Goldsky はマネージド Postgres（Neon）データベースをプロビジョニングし、その認証情報をシークレットとして一度の手順で保存できます。外部データベースのアカウントは必要ありません。

goldsky hosted-sink create --type postgres

• --type postgres は必須です。--name（省略時は HOSTED_POSTGRES_<RANDOM> として自動生成）と --description は省略可能です。
• 成功すると、作成されたシークレットの 名前、ID、タイプ が表示されます。接続文字列は意図的に表示されません。シンクの secret_name にはシークレットの 名前 を指定するか、後から接続文字列を確認するには goldsky secret reveal <name> を実行してください。
• Scale プラン以上が必要です。利用権限がない場合、チームの請求ページを案内する Scale プランへのアップグレードメッセージとともにコマンドが失敗します。その場合は、以下の外部 Postgres を用意する方法に切り替えてください。

Neon：

• 接続文字列の形式：postgresql://USER:[email protected]/neondb
• デフォルトのポート：5432
• よくある問題：無料プランには 512MB の上限があり、「project size limit exceeded」によりパイプラインが失敗します

Supabase：

• 接続文字列の形式：postgresql://postgres:[email protected]:5432/postgres
• Project Settings → Database から「Connection string」を使用します

PlanetScale（MySQL）：

• "protocol": "mysql" とポート 3306 を使用します

ステップ 5：シークレットを直接作成する

認証情報を取得したら（解析またはユーザーからの入力）、すぐに作成します。

goldsky secret create \
  --name SECRET_NAME \
  --value '{"type":"jdbc","protocol":"postgres",...}' \
  --description "Optional description"

命名規則： PROJECT_PROVIDER（例：TRADEWATCH_NEON、ANALYTICS_SUPABASE）

ステップ 6：確認する

goldsky secret list を実行して、作成されたことを確認します。

---

シークレットの種類

各シークレットの種類は、type フィールドの値に対応します。各種類のフィールド仕様と例については、ドキュメントのシークレット形式を参照してください。

シークレットの種類	Type フィールド	用途
PostgreSQL	jdbc	データベースシンク
MySQL	jdbc	データベースシンク（プロトコル：mysql）
ClickHouse	clickHouse	分析データベース
Kafka	kafka	イベントストリーミング
AWS S3	s3	オブジェクトストレージ
Google Pub/Sub	pubsub	GCP Pub/Sub トピック（Turbo 専用）
ElasticSearch	elasticSearch	検索エンジン
DynamoDB	dynamodb	NoSQL データベース
SQS	sqs	メッセージキュー
OpenSearch	opensearch	検索／分析
Webhook	httpauth	HTTP エンドポイント

クイックリファレンスの例

PostgreSQL — 接続文字列の形式：

postgres://username:password@host:port/database

goldsky secret create --name MY_POSTGRES_SECRET
# The CLI will prompt for the connection string interactively

ClickHouse — 接続文字列の形式：

https://username:password@host:port/database

Kafka — JSON 形式：

{
  "type": "kafka",
  "bootstrapServers": "broker:9092",
  "securityProtocol": "SASL_SSL",
  "saslMechanism": "PLAIN",
  "saslJaasUsername": "user",
  "saslJaasPassword": "pass"
}

S3 — コロン区切りの形式：

access_key_id:secret_access_key

または、セッショントークンを含む場合：access_key_id:secret_access_key:session_token

Google Cloud Pub/Sub — JSON 形式（Turbo 専用）：

{
  "type": "pubsub",
  "projectId": "goldsky-prod",
  "credentialsJson": "{\"type\":\"service_account\",\"project_id\":\"goldsky-prod\",...}"
}

CLI は GCP プロジェクト ID の入力を求め、サービスアカウントの JSON キー全体を 1 行で貼り付けるよう求めます。貼り付けた内容が type === "service_account" を満たす JSON であることを検証します。

**IAM の要件：**サービスアカウントには roles/pubsub.publisher と roles/pubsub.viewer の両方が必要です。初期化時にシンクがトピックの存在を事前確認するため、viewer ロールが必要です。公開権限のみを持つサービスアカウントでは、PermissionDenied エラーが発生してシンクの初期化に失敗します。

パイプラインをデプロイする前に、GCP プロジェクト内に Pub/Sub トピックが存在している必要があります。Goldsky はトピックを自動作成しません。

Webhook：

**注：**Turbo パイプラインの Webhook シンクは、Goldsky のネイティブなシークレット管理に対応していません。代わりに、パイプライン YAML の headers: フィールドに認証ヘッダーを直接記述してください。

接続文字列パーサー

PostgreSQL では、接続文字列の解析にヘルパースクリプトを使用します。

./scripts/parse-connection-string.sh "postgresql://user:pass@host:5432/dbname"
# Output: JSON ready for goldsky secret create --value

ステップ 5：確認して作成

作成される内容をユーザーに表示し（パスワードは *** でマスク）、コマンドを実行する前に確認を求めます。

ステップ 6：成功を確認

goldsky secret list を実行して、シークレットが作成されたことを確認します。

クイックリファレンス

操作	コマンド
作成	goldsky secret create --name NAME --value "value"
一覧表示	goldsky secret list
表示	goldsky secret reveal NAME
更新	goldsky secret update NAME --value "$(cat /secure/path/secret.json)"
削除	goldsky secret delete NAME

前提条件

• Goldsky CLI がインストールされていること
• ログイン済みであること（goldsky login）
• 接続先シンクの接続認証情報

シークレットが必要な理由

外部シンク（PostgreSQL、ClickHouse、Kafka、S3）に書き込むパイプラインでは、接続用の認証情報が必要です。認証情報をパイプライン YAML に直接記述する代わりに、シークレットとして保存し、名前で参照します。

メリット：

• 認証情報は暗号化され、安全に保存されます
• シークレットを公開せずにパイプライン設定を共有できます
• パイプラインを変更せずに認証情報をローテーションできます

コマンドリファレンス

コマンド	目的	主なフラグ
goldsky secret create	新しいシークレットを作成	--name、--value、--description
goldsky secret list	すべてのシークレットを一覧表示
goldsky secret reveal <name>	シークレットの値を表示
goldsky secret update <name>	シークレットの値を更新	--value、--description
goldsky secret delete <name>	シークレットを削除	-f（強制実行、確認を省略）

よくあるパターン

PostgreSQL シークレット

goldsky secret create --name PROD_POSTGRES
# When prompted, provide the connection string:
# postgres://admin:[email protected]:5432/mydb

パイプラインでの使用：

sinks:
  output:
    type: postgres
    from: my_source
    schema: public
    table: transfers
    secret_name: PROD_POSTGRES

ClickHouse シークレット

goldsky secret create --name CLICKHOUSE_ANALYTICS
# When prompted, provide the connection string:
# https://default:[email protected]:8443/analytics

パイプラインでの使用：

sinks:
  output:
    type: clickhouse
    from: my_source
    table: events
    secret_name: CLICKHOUSE_ANALYTICS
    primary_key: id

認証情報のローテーション

既存のシークレットをその場で更新し、名前とパイプラインの参照を維持します。update --value には、type を含む完全なシークレット JSON オブジェクトが必要です。生の接続文字列は受け付けず、値の入力を求めることもありません。メタデータのみを更新する場合は、--value を指定せずに --description を使用します。

適切なシークレット形式を使用して、所有者のみが読み取れるローカルファイル（たとえば、モード 600 の /secure/path/secret.json）に JSON を用意します。PostgreSQL では、JDBC フィールド type、protocol、host、port、databaseName、user、password を使用します。

goldsky secret update MY_POSTGRES_SECRET --value "$(cat /secure/path/secret.json)"

これにより値がシェルの履歴に残ることはありませんが、CLI には引き続き argv 経由で渡されるため、プロセス一覧から見える可能性があります。シェルのトレースを無効にし、ファイルや展開後のコマンドを決して表示しないでください。一時的な認証情報ファイルは使用後に削除してください。ローテーション後にパイプラインの接続を確認してください。シークレットの更新に成功しただけで、実行中のパイプラインに認証情報が再読み込みされたと判断しないでください。

未使用のシークレットの削除

# With confirmation prompt
goldsky secret delete OLD_SECRET

# Skip confirmation (for scripts)
goldsky secret delete OLD_SECRET -f

警告： 使用中のシークレットを削除すると、パイプラインで障害が発生します。

シークレットの命名規則

説明的で、大文字とアンダースコアを使った名前にしてください。

良い例	悪い例
PROD_POSTGRES_MAIN	secret1
STAGING_CLICKHOUSE	my-secret
KAFKA_PROD_CLUSTER	postgres

わかりやすくするため、名前には環境と用途を含めてください。

トラブルシューティング

エラー：シークレットが見つかりません

Error: Secret 'MY_SECRET' not found

原因： シークレット名が存在しないか、スペルが間違っています。
対処法： goldsky secret list を実行して利用可能なシークレットを確認し、正確な名前を確認してください。

エラー：シークレットはすでに存在します

Error: Secret 'MY_SECRET' already exists

原因： すでに使用されている名前でシークレットを作成しようとしています。
対処法： 認証情報のローテーションに従って既存のシークレットを更新するか、別のシークレットには異なる名前を選んでください。

エラー：シークレット値の形式が無効です

Error: Invalid JSON in secret value

原因： シークレット値の JSON 構文エラーです。
対処法： シークレットを作成する前に、JSON を検証してください。

# Test JSON validity
echo '{"url":"...","user":"..."}' | jq .

パイプラインで「connection refused」が発生します

原因： シークレット内の認証情報が正しくないか、データベースに到達できません。
対処法：

1. Goldsky の外部で認証情報が機能することを確認します：psql "postgresql://..."
2. シークレットの値を確認します：goldsky secret reveal MY_SECRET
3. データベースが Goldsky の IP 範囲からの接続を許可していることを確認します

パイプラインで「authentication failed」が発生します

原因： シークレット内のユーザー名またはパスワードが正しくありません。 対処法： 認証情報のローテーションを使用して、正しい認証情報で既存のシークレットを更新します。

シークレット値に特殊文字が含まれています

原因： 特殊文字を含む JSON 文字列は、適切にエスケープする必要があります。 対処法： パスワードフィールド内の特殊文字を適切にエスケープしてください。

• バックスラッシュ：\\ を使用します
• 二重引用符：\" を使用します
• 改行：\n を使用します

構造化された JSON 形式では、パスワードは独立したフィールドであるため、ほとんどの特殊文字は URL エンコードなしで使用できます。

関連

• /turbo-builder — これらのシークレットを使用するビルドおよびデプロイのパイプライン
• /auth-setup — ユーザーがログインしていない場合に呼び出します
• /turbo-pipelines — パイプラインの YAML 設定リファレンス