From c3b5bd514d1174867e58f0c6238a76f18979fb93 Mon Sep 17 00:00:00 2001 From: James Date: Sat, 20 Jun 2026 10:29:11 +1000 Subject: [PATCH 1/2] docs: clarify BYOK KMS needs decrypt-only and identity may not be in dashboard Two clarifications to the secret-encryption section of the flowctl concept page: - The data plane identity needs decrypt access only (roles/cloudkms.cryptoKeyDecrypter on GCP KMS), not encrypt. Estuary only decrypts configs at connector run time. - Auto-encryption (flowctl and the dashboard) uses Estuary's managed key, so using your own key requires encrypting the config manually before publishing. - For cross-cloud KMS (for example a GCP KMS key with an AWS data plane), the identity to grant is not surfaced in the dashboard; contact Estuary support for it. --- site/docs/concepts/flowctl.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/site/docs/concepts/flowctl.md b/site/docs/concepts/flowctl.md index 248c0850bda..76c40145337 100644 --- a/site/docs/concepts/flowctl.md +++ b/site/docs/concepts/flowctl.md @@ -217,6 +217,15 @@ You can find the image name and latest tag in the connector's [reference](/refer These commands use the same encryption mechanism as the dashboard and ensure that your secrets are encrypted whenever you send your specifications to Estuary. +:::note +Auto-encryption uses Estuary's managed encryption key, not a customer-managed +(bring-your-own) KMS key. To encrypt your configurations with your own key, you +must encrypt them yourself before publishing, as described in +[Controlling encryption with `sops`](#controlling-encryption-with-sops). A +plain-text config published without manual encryption is encrypted with Estuary's +default key, and your own key is not used. +::: + This does not, by default, encrypt secrets in your local environment. If you want to encrypt local files, you can overwrite your local plain-text configuration with Estuary's encrypted version. To do so, run: @@ -240,11 +249,18 @@ been encrypted. Estuary supports customers encrypting secrets with keys from AWS Key Management Service, Google Cloud Platform KMS, and Azure Key Vault. :::important -When deploying catalogs onto the managed Estuary runtime, you must grant access to -decrypt your KMS key to the appropriate identity for your data plane and KMS. -These identities vary by data plane, find yours under -[Admin > Settings > Data Planes](https://dashboard.estuary.dev/admin/settings) -in the Estuary dashboard. +When deploying catalogs onto the managed Estuary runtime, you must grant **decrypt** +access on your KMS key to the appropriate identity for your data plane. On GCP KMS, +this is the `roles/cloudkms.cryptoKeyDecrypter` role. Estuary only decrypts your +configuration at connector run time and never encrypts with your key, so the +identity does not need encrypt access. + +These identities vary by data plane. You can find your data plane's native-cloud +identity under [Admin > Settings > Data Planes](https://dashboard.estuary.dev/admin/settings) +in the Estuary dashboard. If your KMS provider differs from the cloud your data +plane runs in (for example, encrypting with a GCP KMS key while your data plane +runs on AWS), the identity you need may not be shown in the dashboard. Contact +Estuary support to obtain it. ::: The examples below provide a useful reference. From 6ceb3b84366282dcb2df9c207fca427e74cbe891 Mon Sep 17 00:00:00 2001 From: James Date: Sat, 20 Jun 2026 10:46:59 +1000 Subject: [PATCH 2/2] docs: make BYOK KMS grant guidance provider-specific (GCP/AWS/Azure) The grant mechanism differs by provider, so the decrypt-only note now covers all three: GCP IAM role binding (cryptoKeyDecrypter), AWS key-policy statement (kms:Decrypt), and Azure Key Vault access policy. Each data plane carries an identity for all three clouds, so the cross-cloud case is stated explicitly. --- site/docs/concepts/flowctl.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/site/docs/concepts/flowctl.md b/site/docs/concepts/flowctl.md index 76c40145337..b6b05979c20 100644 --- a/site/docs/concepts/flowctl.md +++ b/site/docs/concepts/flowctl.md @@ -249,18 +249,22 @@ been encrypted. Estuary supports customers encrypting secrets with keys from AWS Key Management Service, Google Cloud Platform KMS, and Azure Key Vault. :::important -When deploying catalogs onto the managed Estuary runtime, you must grant **decrypt** -access on your KMS key to the appropriate identity for your data plane. On GCP KMS, -this is the `roles/cloudkms.cryptoKeyDecrypter` role. Estuary only decrypts your -configuration at connector run time and never encrypts with your key, so the -identity does not need encrypt access. - -These identities vary by data plane. You can find your data plane's native-cloud -identity under [Admin > Settings > Data Planes](https://dashboard.estuary.dev/admin/settings) -in the Estuary dashboard. If your KMS provider differs from the cloud your data -plane runs in (for example, encrypting with a GCP KMS key while your data plane -runs on AWS), the identity you need may not be shown in the dashboard. Contact -Estuary support to obtain it. +When deploying catalogs onto the managed Estuary runtime, you must grant **decrypt-only** +access on your KMS key to the appropriate identity for your data plane. Estuary +decrypts your configuration only at connector run time and never encrypts with your +key, so the identity never needs encrypt access. How you grant access depends on the +provider: + +- **GCP KMS**: grant the `roles/cloudkms.cryptoKeyDecrypter` role on the key to the data plane's GCP service account. +- **AWS KMS**: add a key-policy statement allowing `kms:Decrypt` and `kms:DescribeKey` to the data plane's AWS IAM user. +- **Azure Key Vault**: grant a decrypt key permission to the data plane's Azure application. + +Each data plane has a separate identity for GCP, AWS, and Azure, so you can use a KMS +provider that differs from the cloud your data plane runs in (for example, a GCP KMS +key with an AWS data plane). The dashboard surfaces your data plane's native-cloud +identity under [Admin > Settings > Data Planes](https://dashboard.estuary.dev/admin/settings); +the identity for a different provider may not be shown there, so contact Estuary +support to obtain the one you need. ::: The examples below provide a useful reference.