From 45a71eafe89562890737e55741f63cf472576c5e Mon Sep 17 00:00:00 2001 From: Kathryn Hancox Date: Tue, 20 Aug 2024 15:18:09 -0400 Subject: [PATCH] Clarify entire credentials object base64 encoded in pub/sub docs --- src/current/v23.1/changefeed-examples.md | 16 ++++++++-------- src/current/v23.1/changefeed-sinks.md | 4 ++-- src/current/v23.2/changefeed-examples.md | 16 ++++++++-------- src/current/v23.2/changefeed-sinks.md | 4 ++-- src/current/v24.1/changefeed-examples.md | 16 ++++++++-------- src/current/v24.1/changefeed-sinks.md | 4 ++-- src/current/v24.2/changefeed-examples.md | 16 ++++++++-------- src/current/v24.2/changefeed-sinks.md | 4 ++-- 8 files changed, 40 insertions(+), 40 deletions(-) diff --git a/src/current/v23.1/changefeed-examples.md b/src/current/v23.1/changefeed-examples.md index aa0e00e728a..95bd68ffc87 100644 --- a/src/current/v23.1/changefeed-examples.md +++ b/src/current/v23.1/changefeed-examples.md @@ -406,36 +406,36 @@ You'll need access to a [Google Cloud Project](https://cloud.google.com/resource gcloud pubsub subscriptions create movr-users-sub --topic=movr-users --topic-project=cockroach-project ~~~ -1. With the topic and subscription set up, you can now download your Service Account's key. Use the following command to specify where to download the json key file (`key.json`): +1. With the topic and subscription set up, you can now download your Service Account credentials. Use the [`gcloud iam service-accounts keys create`](https://cloud.google.com/sdk/gcloud/reference/iam/service-accounts/keys/create) command to specify where to download the JSON credential file (`credentials.json`): {% include_cached copy-clipboard.html %} ~~~ shell - gcloud iam service-accounts keys create key.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com + gcloud iam service-accounts keys create credentials.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com ~~~ - Next, base64 encode your credentials key using the command specific to your platform. + Next, base64 encode the file that contains the entire JSON credential object using the command specific to your platform. If you're working on macOS: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 + cat credentials.json | base64 ~~~ If you're working on Linux, run the following to ensure that lines are not wrapped in the output: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 -w 0 + cat credentials.json | base64 -w 0 ~~~ - Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the key is base64 encoded before passing it in the URI. + Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the credentials are base64 encoded before passing it in the URI. -1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you pass the base64-encoded credentials for your Service Account: +1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you have base64 encoded the entire credentials JSON object for your Service Account and then run: {% include_cached copy-clipboard.html %} ~~~ sql - CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded key}'; + CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded credentials}'; ~~~ You can include the `region` parameter for your topic, or use the [WITH `unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option for multi-region Pub/Sub. See the [Changefeed Sinks]({% link {{ page.version.version }}/changefeed-sinks.md %}#google-cloud-pub-sub) page for more detail. diff --git a/src/current/v23.1/changefeed-sinks.md b/src/current/v23.1/changefeed-sinks.md index 083d660ce2d..4322304d3e0 100644 --- a/src/current/v23.1/changefeed-sinks.md +++ b/src/current/v23.1/changefeed-sinks.md @@ -212,7 +212,7 @@ For more details, refer to the [Pub/Sub sink messages](#pub-sub-sink-messages) s A Pub/Sub sink URI follows this example: ~~~ -'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded key}' +'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded credentials}' ~~~ @@ -223,7 +223,7 @@ URI Parameter | Description `region` | (Optional) The single region to which all output will be sent. If you do not include `region`, then you must create your changefeed with the [`unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option. `topic_name` | (Optional) The topic name to which messages will be sent. See the following section on [Topic Naming](#topic-naming) for detail on how topics are created. `AUTH` | The authentication parameter can define either `specified` (default) or `implicit` authentication. To use `specified` authentication, pass your [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials with the URI. To use `implicit` authentication, configure these credentials via an environment variable. See [Use Cloud Storage for Bulk Operations]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) for examples of each of these. -`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials. +`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts). `ASSUME_ROLE` | The service account of the role to assume. Use in combination with `AUTH=implicit` or `specified`. {% include {{ page.version.version }}/cdc/options-table-note.md %} diff --git a/src/current/v23.2/changefeed-examples.md b/src/current/v23.2/changefeed-examples.md index e1bf44e4829..2863aaa34cd 100644 --- a/src/current/v23.2/changefeed-examples.md +++ b/src/current/v23.2/changefeed-examples.md @@ -419,36 +419,36 @@ You'll need access to a [Google Cloud Project](https://cloud.google.com/resource gcloud pubsub subscriptions create movr-users-sub --topic=movr-users --topic-project=cockroach-project ~~~ -1. With the topic and subscription set up, you can now download your Service Account's key. Use the following command to specify where to download the json key file (`key.json`): +1. With the topic and subscription set up, you can now download your Service Account credentials. Use the [`gcloud iam service-accounts keys create`](https://cloud.google.com/sdk/gcloud/reference/iam/service-accounts/keys/create) command to specify where to download the JSON credential file (`credentials.json`): {% include_cached copy-clipboard.html %} ~~~ shell - gcloud iam service-accounts keys create key.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com + gcloud iam service-accounts keys create credentials.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com ~~~ - Next, base64 encode your credentials key using the command specific to your platform. + Next, base64 encode the file that contains the entire JSON credential object using the command specific to your platform. If you're working on macOS: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 + cat credentials.json | base64 ~~~ If you're working on Linux, run the following to ensure that lines are not wrapped in the output: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 -w 0 + cat credentials.json | base64 -w 0 ~~~ - Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the key is base64 encoded before passing it in the URI. + Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the credentials are base64 encoded before passing it in the URI. -1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you pass the base64-encoded credentials for your Service Account: +1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you have base64 encoded the entire credentials JSON object for your Service Account and then run: {% include_cached copy-clipboard.html %} ~~~ sql - CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded key}'; + CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded credentials}'; ~~~ You can include the `region` parameter for your topic, or use the [WITH `unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option for multi-region Pub/Sub. See the [Changefeed Sinks]({% link {{ page.version.version }}/changefeed-sinks.md %}#google-cloud-pub-sub) page for more detail. diff --git a/src/current/v23.2/changefeed-sinks.md b/src/current/v23.2/changefeed-sinks.md index b1ba45a3fcd..faf83fabc87 100644 --- a/src/current/v23.2/changefeed-sinks.md +++ b/src/current/v23.2/changefeed-sinks.md @@ -237,7 +237,7 @@ Changefeeds can deliver messages to a Google Cloud Pub/Sub sink, which is integr A Pub/Sub sink URI follows this example: ~~~ -'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded key}' +'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded credentials}' ~~~ @@ -248,7 +248,7 @@ URI Parameter | Description `region` | (Optional) The single region to which all output will be sent. If you do not include `region`, then you must create your changefeed with the [`unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option. `topic_name` | (Optional) The topic name to which messages will be sent. See the following section on [Topic Naming](#topic-naming) for detail on how topics are created. `AUTH` | The authentication parameter can define either `specified` (default) or `implicit` authentication. To use `specified` authentication, pass your [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials with the URI. To use `implicit` authentication, configure these credentials via an environment variable. Refer to the [Cloud Storage Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) page for examples of each of these. -`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials. +`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts). `ASSUME_ROLE` | The service account of the role to assume. Use in combination with `AUTH=implicit` or `specified`. Refer to the [Cloud Storage Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) page for an example on setting up assume role authentication. {% include {{ page.version.version }}/cdc/options-table-note.md %} diff --git a/src/current/v24.1/changefeed-examples.md b/src/current/v24.1/changefeed-examples.md index 5b61c9dc42c..004c133c82b 100644 --- a/src/current/v24.1/changefeed-examples.md +++ b/src/current/v24.1/changefeed-examples.md @@ -417,36 +417,36 @@ You'll need access to a [Google Cloud Project](https://cloud.google.com/resource gcloud pubsub subscriptions create movr-users-sub --topic=movr-users --topic-project=cockroach-project ~~~ -1. With the topic and subscription set up, you can now download your Service Account's key. Use the following command to specify where to download the json key file (`key.json`): +1. With the topic and subscription set up, you can now download your Service Account credentials. Use the [`gcloud iam service-accounts keys create`](https://cloud.google.com/sdk/gcloud/reference/iam/service-accounts/keys/create) command to specify where to download the JSON credential file (`credentials.json`): {% include_cached copy-clipboard.html %} ~~~ shell - gcloud iam service-accounts keys create key.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com + gcloud iam service-accounts keys create credentials.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com ~~~ - Next, base64 encode your credentials key using the command specific to your platform. + Next, base64 encode the file that contains the entire JSON credential object using the command specific to your platform. If you're working on macOS: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 + cat credentials.json | base64 ~~~ If you're working on Linux, run the following to ensure that lines are not wrapped in the output: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 -w 0 + cat credentials.json | base64 -w 0 ~~~ - Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the key is base64 encoded before passing it in the URI. + Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the credentials are base64 encoded before passing it in the URI. -1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you pass the base64-encoded credentials for your Service Account: +1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you have base64 encoded the entire credentials JSON object for your Service Account and then run: {% include_cached copy-clipboard.html %} ~~~ sql - CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded key}'; + CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded credentials}'; ~~~ You can include the `region` parameter for your topic, or use the [WITH `unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option for multi-region Pub/Sub. See the [Changefeed Sinks]({% link {{ page.version.version }}/changefeed-sinks.md %}#google-cloud-pub-sub) page for more detail. diff --git a/src/current/v24.1/changefeed-sinks.md b/src/current/v24.1/changefeed-sinks.md index 633f8bffd8d..b05e6a58d5f 100644 --- a/src/current/v24.1/changefeed-sinks.md +++ b/src/current/v24.1/changefeed-sinks.md @@ -247,7 +247,7 @@ Since CockroachDB v23.2, the `changefeed.new_pubsub_sink_enabled` cluster settin A Pub/Sub sink URI follows this example: ~~~ -'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded key}' +'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded credentials}' ~~~ @@ -258,7 +258,7 @@ URI Parameter | Description `region` | (Optional) The single region to which all output will be sent. If you do not include `region`, then you must create your changefeed with the [`unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option. `topic_name` | (Optional) The topic name to which messages will be sent. See the following section on [Topic Naming](#topic-naming) for detail on how topics are created. `AUTH` | The authentication parameter can define either `specified` (default) or `implicit` authentication. To use `specified` authentication, pass your [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials with the URI. To use `implicit` authentication, configure these credentials via an environment variable. Refer to the [Cloud Storage Authentication page]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) page for examples of each of these. -`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials. +`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts). `ASSUME_ROLE` | The service account of the role to assume. Use in combination with `AUTH=implicit` or `specified`. Refer to the [Cloud Storage Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) page for an example on setting up assume role authentication. {% include {{ page.version.version }}/cdc/options-table-note.md %} diff --git a/src/current/v24.2/changefeed-examples.md b/src/current/v24.2/changefeed-examples.md index 2b32b046a4c..5b7496eba68 100644 --- a/src/current/v24.2/changefeed-examples.md +++ b/src/current/v24.2/changefeed-examples.md @@ -417,36 +417,36 @@ You'll need access to a [Google Cloud Project](https://cloud.google.com/resource gcloud pubsub subscriptions create movr-users-sub --topic=movr-users --topic-project=cockroach-project ~~~ -1. With the topic and subscription set up, you can now download your Service Account's key. Use the following command to specify where to download the json key file (`key.json`): +1. With the topic and subscription set up, you can now download your Service Account credentials. Use the [`gcloud iam service-accounts keys create`](https://cloud.google.com/sdk/gcloud/reference/iam/service-accounts/keys/create) command to specify where to download the JSON credential file (`credentials.json`): {% include_cached copy-clipboard.html %} ~~~ shell - gcloud iam service-accounts keys create key.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com + gcloud iam service-accounts keys create credentials.json --iam-account=cdc-demo@cockroach-project.iam.gserviceaccount.com ~~~ - Next, base64 encode your credentials key using the command specific to your platform. + Next, base64 encode the file that contains the entire JSON credential object using the command specific to your platform. If you're working on macOS: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 + cat credentials.json | base64 ~~~ If you're working on Linux, run the following to ensure that lines are not wrapped in the output: {% include_cached copy-clipboard.html %} ~~~ shell - cat key.json | base64 -w 0 + cat credentials.json | base64 -w 0 ~~~ - Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the key is base64 encoded before passing it in the URI. + Copy the output so that you can add it to your [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) statement in the next step. When you create your changefeed, it is necessary that the credentials are base64 encoded before passing it in the URI. -1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you pass the base64-encoded credentials for your Service Account: +1. Back in the SQL shell, create a changefeed that will emit messages to your Pub/Sub topic. Ensure that you have base64 encoded the entire credentials JSON object for your Service Account and then run: {% include_cached copy-clipboard.html %} ~~~ sql - CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded key}'; + CREATE CHANGEFEED FOR TABLE users INTO 'gcpubsub://cockroach-project?region=us-east1&topic_name=movr-users&AUTH=specified&CREDENTIALS={base64-encoded credentials}'; ~~~ You can include the `region` parameter for your topic, or use the [WITH `unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option for multi-region Pub/Sub. See the [Changefeed Sinks]({% link {{ page.version.version }}/changefeed-sinks.md %}#google-cloud-pub-sub) page for more detail. diff --git a/src/current/v24.2/changefeed-sinks.md b/src/current/v24.2/changefeed-sinks.md index 699cf31b605..2897dcaeada 100644 --- a/src/current/v24.2/changefeed-sinks.md +++ b/src/current/v24.2/changefeed-sinks.md @@ -241,7 +241,7 @@ Since CockroachDB v23.2, the `changefeed.new_pubsub_sink_enabled` cluster settin A Pub/Sub sink URI follows this example: ~~~ -'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded key}' +'gcpubsub://{project name}?region={region}&topic_name={topic name}&AUTH=specified&CREDENTIALS={base64-encoded credentials}' ~~~ @@ -252,7 +252,7 @@ URI Parameter | Description `region` | (Optional) The single region to which all output will be sent. If you do not include `region`, then you must create your changefeed with the [`unordered`]({% link {{ page.version.version }}/create-changefeed.md %}#unordered) option. `topic_name` | (Optional) The topic name to which messages will be sent. See the following section on [Topic Naming](#topic-naming) for detail on how topics are created. `AUTH` | The authentication parameter can define either `specified` (default) or `implicit` authentication. To use `specified` authentication, pass your [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials with the URI. To use `implicit` authentication, configure these credentials via an environment variable. Refer to the [Cloud Storage Authentication page]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) page for examples of each of these. -`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts) credentials. +`CREDENTIALS` | (Required with `AUTH=specified`) The base64-encoded credentials of your Google [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts). `ASSUME_ROLE` | The service account of the role to assume. Use in combination with `AUTH=implicit` or `specified`. Refer to the [Cloud Storage Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) page for an example on setting up assume role authentication. {% include {{ page.version.version }}/cdc/options-table-note.md %}