[DOC-10647] Update Python Todo app

src/current/cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md

@@ -6,50 +6,43 @@ toc_not_nested: true
 docs_area:
 ---
 
-This tutorial shows you how to run a sample To-Do app in [Kubernetes](https://kubernetes.io/) with CockroachDB {{ site.data.products.standard }} as the datastore. The app is written in Python with Flask as the web framework and SQLAlchemy for working with SQL data, and the code is [open-source and forkable](https://github.com/cockroachdb/examples-python/tree/master/flask-sqlalchemy).
+This tutorial shows you how to run a sample To-Do app in [Kubernetes](https://kubernetes.io/) with CockroachDB {{ site.data.products.standard }} as the datastore. The app is written in Python and uses the Flask web framework and SQLAlchemy for working with SQL data. You can view and download the code from [GitHub](https://github.com/cockroachdb/examples-python/tree/master/flask-sqlalchemy).
 
 ## Before you begin
 
-1. If you haven't already, <a href="https://cockroachlabs.cloud/signup?referralId=docs_cc_python_flask" rel="noopener" target="_blank">sign up for a CockroachDB {{ site.data.products.cloud }} account</a>.
+1. Create a [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud/signup?referralId={{page.referral_id}}) account and log in.
 
-1. Install the following tools, if you do not already have them:
+1. [Create a CockroachDB {{ site.data.products.standard }} cluster]({% link cockroachcloud/create-your-cluster.md %}) for the sample To-Do app.
+
+1. On your local system, be sure the following tools are installed:
 
     Tool | Purpose
     -----|--------
     [pip](https://pip.pypa.io/en/stable/installation/) | You'll need pip to install SQLAlchemy and a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL.
     [Docker](https://docs.docker.com/v17.12/docker-for-mac/install/) | You'll dockerize your application for running in Kubernetes.
     [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) | This is the tool you'll use to run Kubernetes locally, for your OS. This includes installing a hypervisor and `kubectl`, the command-line tool used to manage Kubernetes from your local workstation.
 
-1. If you haven't already, [create a CockroachDB {{ site.data.products.standard }} cluster]({% link cockroachcloud/create-your-cluster.md %}).
-
 ## Prepare your cluster
 
-- [Step 1. Authorize your local workstation's network](#step-1-authorize-your-local-workstations-network)
-- [Step 2. Create a SQL user](#step-2-create-a-sql-user)
-- [Step 3. Connect to the cluster](#step-3-connect-to-the-cluster)
-- [Step 4. Create the CockroachDB {{ site.data.products.standard }} database](#step-4-create-the-database)
-- [Step 5. Generate the application connection string](#step-5-generate-the-application-connection-string)
+Follow the steps in this section to prepare your cluster for the example To-DO app.
 
 ### Step 1. Authorize your local workstation's network
 
-Before you connect to your CockroachDB {{ site.data.products.standard }} cluster, you need to authorize your network by adding the public IP address of the workstation to the allowlist. Otherwise, connections from this workstation will be rejected.
-
-Once you are [logged in](https://cockroachlabs.cloud/), you can use the Console to authorize your network:
+Before you can connect to your CockroachDB {{ site.data.products.standard }} cluster, you need to authorize your network by adding the public IP address of the workstation to the [allowlist]({% link cockroachcloud/network-authorization.md %}#ip-allowlisting). Otherwise, connections from this workstation will be rejected.
 
-1. In the left navigation bar, click **Networking**.
-1. Click the **Add Network** button in the right corner. The **Add Network** dialog displays.
+1. In the left navigation bar of the CockroachDB {{ site.data.products.cloud }} Console, click **Networking**.
+1. Click **Add Network**. The **Add Network** dialog displays.
 1. (Optional) Enter a descriptive name for the network.
-1. From the **Network** dropdown, select **Current Network**. Your local machine's IP address will be auto-populated in the box.
-1. Select both networks: **DB Console to monitor the cluster** and **CockroachDB Client to access the databases**.
-
-    The **DB Console** refers to the cluster's DB Console, where you can observe your cluster's health and performance. For more information, see [DB Console Overview]({% link {{site.current_cloud_version}}/ui-overview.md %}).
-
+1. From the **Network** selector, choose **Current Network**. Your local machine's IP address will be auto-populated in the box.
+1. Select both **DB Console to monitor the cluster** and **CockroachDB Client to access the databases**. The first option allows connections from this IP to the cluster's [DB Console]({% link {{site.current_cloud_version}}/ui-overview.md %}), where you can observe your cluster's health and performance. The second option allows SQL clients to connect from this IP.
 1. Click **Apply**.
 
 ### Step 2. Create a SQL user
 
 {% include cockroachcloud/cockroachcloud-ask-admin.md %}
 
+To connect from a SQL client, your cluster must have at least one SQL user. To create a SQL user:
+
 1. In the left navigation bar, click **SQL Users**.
 1. Click **Add User**. The **Add User** dialog displays.
 1. Enter a username and click **Generate & Save Password**.
@@ -58,9 +51,9 @@ Once you are [logged in](https://cockroachlabs.cloud/), you can use the Console
 
     Currently, all new SQL users are created with admin privileges. For more information and to change the default settings, see [Managing SQL users on a cluster]({% link cockroachcloud/managing-access.md %}#manage-sql-users-on-a-cluster).
 
-### Step 3. Connect to the cluster
+### Step 3. Find the cluster's connection details
 
-In this step, you connect both your application and your local system to the cluster.
+In this step, you find the connection details that allow both your application and your local system to connect to the cluster.
 
 1. In the top right corner of the CockroachDB {{ site.data.products.cloud }} Console, click the **Connect** button.
 
@@ -71,15 +64,13 @@ In this step, you connect both your application and your local system to the clu
 
     The **Connect** page of the **Connection info** dialog displays.
 
-1. Select the **Command Line** tab.
+1. Select the **Command Line** tab to find the details you can use to connect from your local workstation's terminal.
 1. If CockroachDB is not installed locally, copy the command to download and install it. In your terminal, run the command.
-1. Select the **Connection string** tab.
+1. Copy the `cockroach sql` command. In the command, add a `:` character after the username and before the `@` character, then paste the password for the SQL user you created earlier. To connect to your cluster from the command line, you can run this command.
+1. Select the **Connection string** tab to find the details you can use to connect from your application.
 1. If the CA certificate for the cluster is not downloaded locally, copy the command to download it. In your terminal, run the command.
-1. Copy the connection string, which begins with `postgresql://`. This will be used to connect your application to CockroachDB {{ site.data.products.standard }}.
+1. Copy the connection string, which begins with `postgresql://`. You will add this string to the example To-Do app so that it can connect to your cluster. In the string, add a `:` character after the username and before the `@` character, then paste the password for the SQL user you created earlier.
 1. Click **Close**.
-1. Use the connection string to connect to the cluster using `cockroach sql`:
-
-    {% include cockroachcloud/sql-connection-string.md %}
 
 ### Step 4. Create the database
 
@@ -92,23 +83,25 @@ On your local workstation's terminal:
     </div>
     <p></p>
 
-1. Use the `cockroach sql` from [Step 3. Connect to the cluster](#step-3-connect-to-the-cluster) to connect to the cluster using the binary you just configured.
+1. Use the **Command Line** `cockroach sql` command to connect to the cluster from a terminal:
 
-1. Create a database `todos`:
+    {% include cockroachcloud/sql-connection-string.md %}
+
+1. After connecting to the cluster, create a database named `todos`:
 
     {% include_cached copy-clipboard.html %}
     ~~~ sql
     > CREATE DATABASE todos;
     ~~~
 
-1. Use database `todos`:
+1. Select the `todos` database:
 
     {% include_cached copy-clipboard.html %}
     ~~~ sql
     > USE todos;
     ~~~
 
-1. Create a table `todos`:
+1. Create a table `todos` with the following schema:
 
     {% include_cached copy-clipboard.html %}
     ~~~ sql
@@ -123,19 +116,6 @@ On your local workstation's terminal:
       );
     ~~~
 
-### Step 5. Generate the application connection string
-
-  1. In the top right corner of the Console, click the **Connect** button.
-
-      The **Connect** dialog displays.
-
-  1. From the **User** dropdown, select the SQL user you created in [Step 2](#step-2-create-a-sql-user).
-  1. Select a **Region** to connect to.
-  1. From the **Database** dropdown, select `todos`.
-  1. On the **Connection String** tab, click **Copy connection string**.
-
-      Copy the application connection string to an accessible location. You will update the password and certificate path in the next step.
-
 ## Build the app
 
 - [Step 1. Configure the sample Python app](#step-1-configure-the-sample-python-app)
@@ -159,11 +139,11 @@ In a new terminal:
     $ cd examples-python/flask-sqlalchemy
     ~~~
 
-1. In the `hello.cfg` file, replace the value for the `SQLALCHEMY_DATABASE_URI` with the application connection string you generated in [Step 5. Generate the application connection string](#step-5-generate-the-application-connection-string) and save the file.
+1. In the `hello.cfg` file, replace the value for the `SQLALCHEMY_DATABASE_URI` with the application connection string you generated in [Step 3. Find the cluster's connection details](#step-3-find-the-clusters-connection-details). Replace `defaultdb` with `todos` to connect to the `todos` database. Save the file.
 
     {% include_cached copy-clipboard.html %}
     ~~~
-    SQLALCHEMY_DATABASE_URI = 'cockroachdb://<username>@<host>:26257/todos?sslmode=verify-full&sslrootcert=$Home/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
+    SQLALCHEMY_DATABASE_URI = 'cockroachdb://{username}:{password}@{host}:26257/todos?sslmode=verify-full&sslrootcert=$Home/Library/CockroachCloud/certs/{cluster-name}-ca.crt'
     ~~~
 
     {{site.data.alerts.callout_info}}
@@ -174,7 +154,7 @@ In a new terminal:
 
 ### Step 2. Test the application locally
 
-1. Install SQLAlchemy, as well as a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL:
+1. Install the following Python packages to satisfy the example app's dependencies. The `sqlalchemy-cockroachdb` package accounts for some differences between CockroachDB and PostgreSQL:
 
     {% include_cached copy-clipboard.html %}
     ~~~ shell
@@ -200,15 +180,7 @@ In a new terminal:
 
 ## Deploy the app
 
-{{site.data.alerts.callout_info}}
-These steps focus on deploying your app locally. For production Kubernetes deployments, use a service like GKE.
-{{site.data.alerts.end}}
-
-- [Step 1. Start a local Kubernetes cluster](#step-1-start-a-local-kubernetes-cluster)
-- [Step 2. Create a Kubernetes secret](#step-2-create-a-kubernetes-secret)
-- [Step 3. Change certificate directory path in configuration file](#step-3-change-certificate-directory-path-in-configuration-file)
-- [Step 4. Dockerize the application](#step-4-dockerize-the-application)
-- [Step 5. Deploy the application](#step-5-deploy-the-application)
+These steps show how to deploy your app locally using Kubernetes.
 
 ### Step 1. Start a local Kubernetes cluster
 
@@ -227,7 +199,8 @@ Create a Kubernetes secret to store the CA certificate you downloaded earlier:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ kubectl create secret generic <username>-secret --from-file $Home/Library/CockroachCloud/certs/<cluster-name>-ca.crt
+$ kubectl create secret generic <username>-secret \
+  --from-file $Home/Library/CockroachCloud/certs/<cluster-name>-ca.crt
 ~~~
 
 Verify the Kubernetes secret was created:
@@ -252,13 +225,9 @@ In the `hello.cfg` file in the `flask-alchemy` folder, replace the certificate d
 SQLALCHEMY_DATABASE_URI = 'cockroachdb://<username>@<host>:26257/todos?sslmode=verify-full&sslrootcert=$Home/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
 ~~~
 
-{{site.data.alerts.callout_info}}
-You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/core/engines.html#sqlalchemy.create_engine) to make sure the [`cockroachdb`](https://github.com/cockroachdb/sqlalchemy-cockroachdb) dialect is used. Using the `postgres://` URL prefix to connect to your CockroachDB cluster will not work.
-{{site.data.alerts.end}}
-
-### Step 4. Dockerize the application
+### Step 4. Create a container with the application
 
-1. In the `flask-sqlalchemy` folder, create a file named `Dockerfile` and copy the following code into the file:
+1. In the `flask-sqlalchemy` folder, create a file named `Dockerfile` with the following contents:
 
     {% include_cached copy-clipboard.html %}
     ~~~
@@ -307,7 +276,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat
 
 ### Step 5. Deploy the application
 
-1. In the `flask-alchemy` folder, create a file named `app-deployment.yaml` and copy the following code into the file. Replace the `<username>` placeholder with the SQL user's username that you created  [while preparing the cluster](#step-2-create-a-sql-user):
+1. In the `flask-alchemy` folder, create a file named `app-deployment.yaml` and copy the following code into the file. Replace the `{username}` placeholder with the SQL user's username that you created [while preparing the cluster](#step-2-create-a-sql-user):
 
     {% include_cached copy-clipboard.html %}
     ~~~
@@ -342,7 +311,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat
           volumes:
           - name: ca-certs
             secret:
-              secretName: <username>-secret
+              secretName: {username}-secret
     ---
     apiVersion: v1
     kind: Service
@@ -372,7 +341,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat
     service/appdeploy created
     ~~~
 
-1. Verify that the deployment and server were created:
+1. Verify that the deployment is ready and the load balancer service is pending:
 
     {% include_cached copy-clipboard.html %}
     ~~~ shell
@@ -440,7 +409,7 @@ You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.creat
 
 1. On the Console, navigate to the cluster's **Tools** page and click **Open DB Console**.
 
-    You can also access the DB Console by navigating to `https://<cluster-name>crdb.io:8080/#/metrics/overview/cluster`. Replace the `<cluster-name>` placeholder with the name of your cluster.
+    You can also access the DB Console by navigating to `https://{cluster-name}crdb.io:8080/#/metrics/overview/cluster`. Replace `<cluster-name>` with the name of your cluster.
 
 1. Enter the SQL user's username and password you created while [preparing the cluster](#step-2-create-a-sql-user).
 

src/current/cockroachcloud/tools-page.md

@@ -13,7 +13,7 @@ The **Tools** page is accessible on CockroachDB {{ site.data.products.standard }
 
 To view the **Tools** page, select a cluster from the [**Clusters** page]({% link cockroachcloud/cluster-management.md %}#view-clusters-page), and click **Tools** in the **Monitoring** section of the left side navigation.
 
-## Monitor CockroachDB {{ site.data.products.cloud }} with Datadog
+## Monitor CockroachDB Cloud with Datadog
 
 The [CockroachDB {{ site.data.products.cloud }} integration for Datadog](https://docs.datadoghq.com/integrations/cockroachdb_dedicated/) enables data collection and alerting on a [subset of CockroachDB metrics](#available-metrics) available at the [Prometheus endpoint]({% link {{site.current_cloud_version}}/monitoring-and-alerting.md %}#prometheus-endpoint), using the Datadog platform.
 

src/current/v24.2/cloud-storage-authentication.md

@@ -58,7 +58,7 @@ To use `implicit` authentication on a CockroachDB {{ site.data.products.cloud }}
 
 ### Use implicit authentication with your own IAM role
 
-For self-hosted deployments, follow these instructions. For CockroachDB {{ site.data.products.advanced }} deployments, you can either follow these instructions or you can [use implicit authentication together with the service account that CockroachDB {{ site.data.products.cloud }} automatically creates](/docs/v23.2/cloud-storage-authentication.html?filters=aws#use-implicit-authentication-advanced).
+For self-hosted deployments, follow these instructions. For CockroachDB {{ site.data.products.advanced }} deployments, you can either follow these instructions or you can [use implicit authentication together with the service account that CockroachDB {{ site.data.products.cloud }} automatically creates](#use-implicit-authentication-advanced).
 
 To limit the control access to your Amazon S3 buckets, you can create IAM roles for users to assume. IAM roles do not have an association to a particular user. The role contains permissions that define the operations a user (or [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)) can complete. An IAM user can then assume a role to undertake a CockroachDB backup, restore, import, etc. As a result, the IAM user only has access to the assigned role, rather than having unlimited access to an S3 bucket.