[MSO docs] End-to-end MSO tutorials for Python and Kubernetes #4918
Conversation
|
This change is |
Amruta-Ranade
changed the title
v19.1/managed-build-a-python-app.md
Outdated
| 4. In the **Password** field, enter `Q7gc8rEdS`. | ||
| 5. Click **Create**. | ||
|
|
||
| Currently, all new users are created with full privileges. For more information and to change the default settings, see [Granting privileges](managed-authorization.html#granting-privileges) and [Using roles](managed-authorization.html#using-roles). |
There was a problem hiding this comment.
Say "with admin privileges" (or "as a member of the admin role") instead of "with full privileges" to match the language used elsewhere.
v19.1/managed-build-a-python-app.md
Outdated
| The CIDR notation is constructed from an IP address (e.g., `192.168.15.161`), a slash (`/`), and a number (e.g., `32`). The number is the count of leading 1-bits in the network identifier. For the example above, the IP address is 32-bits and the number is `32`, so the full IP address is also the network identifier. For more information see Digital Ocean's [Understanding IP Addresses, Subnets,and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). | ||
|
|
||
| You can use `0.0.0.0/0`, which allows all networks. Use this with caution; anybody who uses your password will be able to access the database, and your cluster will be more exposed if there's ever a security bug. The firewall is an extra layer of defense. | ||
|
|
There was a problem hiding this comment.
Add that IPv6 is not currently supported (right?)
v19.1/managed-build-a-python-app.md
Outdated
|
|
||
| <img src="{{ 'images/v19.1/managed/add-network-modal.png' | relative_url }}" alt="Add network" style="border:1px solid #eee;max-width:100%" /> | ||
|
|
||
| 3. Enter the public IP address of the machine in the **Network** field. |
There was a problem hiding this comment.
Should we explain more about what "the machine" is? (talk about your local computer vs a cloud vm)
v19.1/managed-build-a-python-app.md
Outdated
| <img src="{{ 'images/v19.1/managed/add-user-modal.png' | relative_url }}" alt="Add user" style="border:1px solid #eee;max-width:100%" /> | ||
|
|
||
| 3. In the **Username** field, enter `maxroach`. | ||
| 4. In the **Password** field, enter `Q7gc8rEdS`. |
There was a problem hiding this comment.
This sounds like you have to use maxroach and this password. I'd tell the user to choose their own username and password, with a parenthetical "For this example, we'll use maxroach and Q7gc8rEdS". We might want the example password to be something obviously bad like password1234.
v19.1/managed-build-a-python-app.md
Outdated
|
|
||
| ## Step 3: Generate the CockroachDB client connection string | ||
|
|
||
| On the machine where you want to run your application: |
There was a problem hiding this comment.
This step will probably be done on your local workstation (because that's where you have a web browser), not necessarily on the machine where you'll be running the application.
v19.1/managed-build-a-python-app.md
Outdated
| > USE todos; | ||
| ~~~ | ||
|
|
||
| 3. Create a table `todos`: |
There was a problem hiding this comment.
This works (and it's simpler than introducing another tool), but most users will want to use some sort of schema migration tool like alembic or sqlalchemy-migrate. We may want to build this into a future version of the example app and then move the table creation down below so it uses the application connection string.
v19.1/managed-build-a-python-app.md
Outdated
| $ python hello.py | ||
| ~~~ | ||
|
|
||
| The application should run at [http://localhost:80](http://localhost:80) |
There was a problem hiding this comment.
I think it runs on localhost:5000 by default, not localhost:80 (:80 is only allowed if the application is running as root, which is not recommended).
v19.1/managed-dockerize-your-app.md
Outdated
|
|
||
| ## Create a Docker image for the application | ||
|
|
||
| 1. In the `flask-python` folder you created while [building the python application](managed-build-a-python-app.html), create the file names `dockerfile` and copy the following code into the file: |
There was a problem hiding this comment.
"the file names dockerfile" -> "a file named Dockerfile".
We should just add this to the examples repo instead of asking the user to create it here.
| $ docker build -t appdocker . | ||
| ~~~ | ||
|
|
||
| 4. Verify the image was created: |
There was a problem hiding this comment.
For anything but minikube, you'll also need to push this image somewhere. This is going to vary depending on which container registry you're using, but it's probably worth mentioning here that this is where you'd do it (and then you'd change the image:appdocker line below accordingly)
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ shell | ||
| $ minikube start |
There was a problem hiding this comment.
I'm not sure minikube is that interesting to the managed audience. I'd expect this doc to be mainly about a managed k8s service like GKE or amazon's equivalent.
There was a problem hiding this comment.
Reviewable status:
complete! 0 of 0 LGTMs obtained (waiting on @bdarnell and @DuskEagle)
v19.1/managed-build-a-python-app.md, line 23 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
Should we explain more about what "the machine" is? (talk about your local computer vs a cloud vm)
Done.
v19.1/managed-build-a-python-app.md, line 34 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
Add that IPv6 is not currently supported (right?)
Done.
v19.1/managed-build-a-python-app.md, line 51 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
This sounds like you have to use maxroach and this password. I'd tell the user to choose their own username and password, with a parenthetical "For this example, we'll use
maxroachandQ7gc8rEdS". We might want the example password to be something obviously bad likepassword1234.
The idea here was to have a copy-pastable tutorial, where we provide all the values (as far as possible). We do have a generic how-to where we ask them to choose the username/password they want.
v19.1/managed-build-a-python-app.md, line 54 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
Say "with admin privileges" (or "as a member of the
adminrole") instead of "with full privileges" to match the language used elsewhere.
Done.
v19.1/managed-build-a-python-app.md, line 58 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
This step will probably be done on your local workstation (because that's where you have a web browser), not necessarily on the machine where you'll be running the application.
Actually, all the steps are being done on the local workstation. I think I can just remove the line so as to not confuse the user.
v19.1/managed-build-a-python-app.md, line 74 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
If you save the cert in
~/.cockroach-certs/ca.crt,cockroach sqlshould pick it up automatically (without editing the certs dir into the url). However, this doesn't work with any other tools or with multiple clusters, so I'm not sure it's worth talking about here.
Yeah, I am not sure about this step - it's a carryover from the existing "Connect to your cluster" docs that I haven't updated yet. In the process of learning how to build an app, I had to move the certs to the folder containing the application code - again, not sure if that's required or was just my lack of knowledge. And K8s secret (in the next tutorial) required me to provide the absolute path for the certs file anyways. So to summarize, I am not sure if we need this step the way it is written :)
v19.1/managed-build-a-python-app.md, line 78 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
In the previous step, you downloaded the ca.crt to your local workstation, so this part needs to be on the local workstation too (or you need to add a step to copy the ca.crt to whichever machine you're going to use to run the sql client). This also implies the local workstation's IP needs to be whitelisted for SQL use.
Done. Also, is "local workstation" the right phrase? I am used to "local machine" but saw "local workstation" in CRDB docs and went with it. Which one sounds better?
v19.1/managed-build-a-python-app.md, line 127 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
It'll be nice when we have database creation in the MSO console to eliminate this step. We might even want to recommend that they just use
defaultdbto avoid this sequence of steps entirely for the tutorial.
I kinda like including the steps to create and use a database.
v19.1/managed-build-a-python-app.md, line 141 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
This works (and it's simpler than introducing another tool), but most users will want to use some sort of schema migration tool like
alembicorsqlalchemy-migrate. We may want to build this into a future version of the example app and then move the table creation down below so it uses the application connection string.
I actually spent a lot of time making this tutorial work with the movr application because I wanted to include steps for imports and migrations, but abandoned it since it got too complicated and changed the focus from "Get started with MSO from scratch" to figuring out how roles work. I do plan on making a follow-up tutorial that talks about imports and migrations. Will need your help to choose the migration tools to showcase.
v19.1/managed-build-a-python-app.md, line 221 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
I think it runs on
localhost:5000by default, notlocalhost:80(:80is only allowed if the application is running asroot, which is not recommended).
Ahh..good catch. Done.
v19.1/managed-dockerize-your-app.md, line 17 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
"the file names
dockerfile" -> "a file namedDockerfile".We should just add this to the examples repo instead of asking the user to create it here.
Done. And yes!
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 25 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
I'm not sure
minikubeis that interesting to the managed audience. I'd expect this doc to be mainly about a managed k8s service like GKE or amazon's equivalent.
Yes, I do plan on writing more advanced tutorials (for example, working on Google App Engine tutorial now). The original prompt for this tutorial was explaining how to use the Kubernetes secret for custom CA certs and reuse the procedure for CRDB K8s docs. Since I wanted to focus on that, I kept the K8s setup simple. But I agree we need tutorials that represent real-world scenarios. Will continue working on those.
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 73 at r2 (raw file):
Previously, bdarnell (Ben Darnell) wrote…
For anything but
minikube, you'll also need to push this image somewhere. This is going to vary depending on which container registry you're using, but it's probably worth mentioning here that this is where you'd do it (and then you'd change theimage:appdockerline below accordingly)
Yep..will include it in the advanced tutorials.
|
Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/9e566ac1da5d4de448b01b18fb7ed6ccf508aa02/ Edited pages: |
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-dockerize-your-app.md, line 11 at r3 (raw file):
1. Follow Docker's [documentation](https://docs.docker.com/v17.12/docker-for-mac/install/) to install Docker. 2. Build the sample Python application:
nit: Maybe a period here?
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 17 at r3 (raw file):
{{site.data.alerts.callout_info}}Make sure you install <code>minikube</code> version 0.21.0 or later. Earlier versions do not include a Kubernetes server that supports the <code>maxUnavailability</code> field and <code>PodDisruptionBudget</code> resource type used in the CockroachDB StatefulSet configuration.{{site.data.alerts.end}} 3. Build the sample Python application:
This section appears in the "Dockerize your application" section in the previous tutorial. Maybe we could just refer to that?
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 28 at r3 (raw file):
~~~ ## Step 2: Dockerize your application
Again, maybe just refer to the other page instead of copying this information here. If I'm following through each of the tutorials in order seeing this information again is unnecessary.
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 43 at r3 (raw file):
ADD . /app # execute everyone's favorite pip command, pip install -r
This comment is a little confusing? We're not running this until several more lines down.
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 84 at r3 (raw file):
{% include copy-clipboard.html %} ~~~ shell $ kubectl create secret generic maxroach-secret --from-file <absolute path to the CA certificate>
The CA certificate isn't mentioned on this page, so I don't think it would be clear to an end user what this is referring to.
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 142 at r3 (raw file):
~~~ ## Step 6: Run the `kubectl` commands
Maybe "Create the deployment with kubectl"?
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-dockerize-your-app.md, line 11 at r3 (raw file):
Previously, DuskEagle (Joel Kenny) wrote…
nit: Maybe a period here?
I meant it to be the heading for the following para, but I agree that wasn't very clear. Reformatted it.
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 17 at r3 (raw file):
Previously, DuskEagle (Joel Kenny) wrote…
This section appears in the "Dockerize your application" section in the previous tutorial. Maybe we could just refer to that?
I included all the steps in the K8s tutorial because I am not sure if we need the "Dockerize your application" tutorial. I wrote it as an after-thought. What's your opinion about it? Will people find it useful? (As in, do people care about dockerizing their applications?)
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 43 at r3 (raw file):
Previously, DuskEagle (Joel Kenny) wrote…
This comment is a little confusing? We're not running this until several more lines down.
Excellent catch! I think I included the wrong file! Correcting it now.
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 84 at r3 (raw file):
Previously, DuskEagle (Joel Kenny) wrote…
The CA certificate isn't mentioned on this page, so I don't think it would be clear to an end user what this is referring to.
True. Another excellent catch :)
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 142 at r3 (raw file):
Previously, DuskEagle (Joel Kenny) wrote…
Maybe "Create the deployment with
kubectl"?
Yes! Thank you!
|
Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/72615591edf1e4b2811d77c0de848f0753fc6689/ Edited pages: |
There was a problem hiding this comment.
This is a great start, @Amruta-Ranada. However, I don't think the "end-to-end" tutorial aspect comes across the way you've broken this down into separate pages with pre-requisites, etc.
As a next step, I'd suggest you try to present this as a single tutorial called something like:Build a Kubernetes-based Python App on Managed CockoachDB or just Build a Python App on Managed CockroachDB. Not sure of the right title. But I think it's important to present this as a single-page tutorial to make it easy for users to work from start to finish.
Happy to meet in person and think through the possible changes that will get you there.
Reviewable status:
Amruta-Ranade
force-pushed
the
MSO_tutorials
branch
from
8a46a74 to
f88ba66
Compare
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 8 at r4 (raw file):
--- This tutorial shows you how build a [sample To-Do app](https://github.com/cockroachdb/examples-python/tree/master/flask-sqlalchemy) application on your local workstation with Managed CockroachDB using [SQLAlchemy](https://docs.sqlalchemy.org/en/latest/)and the [Kubernetes](http://kubernetes.io/) orchestration system.
Add a space after SQLAlchemy
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 81 at r4 (raw file):
This is how you will access the built-in SQL client later. You will need to replace the `<certs_dir>` placeholders with the path to your `certs` directory.
I might add that they should save this somewhere for later so they don't have to come back later. Since they're following this tutorial, it'll get lost as soon as they click the next "Copy to clipboard" button.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 134 at r4 (raw file):
~~~ shell $ cockroach sql --url 'postgres://maxroach@<region>.<cluster_name>:26257/defaultdb?sslmode=verify-full&sslrootcert=<certs_dir>/<ca.crt>' ~~~
The SQL shell asked me to "Enter password" before I could create a database. I'm getting stuck here. Will reach out
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 140 at r4 (raw file):
{% include copy-clipboard.html %} ~~~ sql > create database todos;
Format: CREATE DATABASE todos;
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 143 at r4 (raw file):
~~~ 3. Use database `todos`:
Maybe clarify - "Set todos as the default database:"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 155 at r4 (raw file):
~~~ sql > CREATE TABLE todos ( todo_id INT8 NOT NULL DEFAULT unique_rowid(),
I think these lines should all be indented
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 171 at r4 (raw file):
The **Connect** modal displays. <img src="{{ 'images/v19.1/managed/connect-modal.png' | relative_url }}" alt="Connect to cluster" style="border:1px solid #eee;max-width:100%" />
This image shows the "Connect from Shell" tab, not the "Connect Your App" tab.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 182 at r4 (raw file):
## Step 6: Configure the sample Python app 1. In a new tab, install SQLAlchemy:
Change to: "In a new terminal tab"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 200 at r4 (raw file):
~~~ 3. Navigate to the flask-alchemy folder:
Suggested change to: "Navigate to the falst-alchemy directory:"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 207 at r4 (raw file):
~~~ 4. In the `hello.cfg` file, replace the value for the `SQLALCHEMY_DATABASE_URI` with the application connection string you generated in Step 5.
"Step 5" is a little confusing since there are multiple Step 5s and a section called Step 5. Maybe say "generated in Step 5. Generate the application connection string" and add a link?
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 220 at r4 (raw file):
## Step 7: Start a local Kubernetes cluster {% include copy-clipboard.html %}
Add some intro: "On your local workstation's terminal:"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 227 at r4 (raw file):
## Step 8: Dockerize your application 1. In the `flask-python` folder you created Step 6, create the file names `dockerfile` and copy the following code into the file:
I would also link to Step 6 here and maybe include the rest of the section title
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 271 at r4 (raw file):
## Step 9: Create a Kubernetes secret Create a Kubernetes secret to store the CA certificate you downloaded in Step 3:
I would also link to Step 3 here and maybe include the rest of the section title
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 280 at r4 (raw file):
## Step 10: Create the deployment files Create a file `app-deployment.yaml` and copy the following code into the file:
Do you need to save this file in a specific location?
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 335 at r4 (raw file):
## Step 11: Create the deployment with `kubectl` {% include copy-clipboard.html %}
Add some intro: "On your local workstation's terminal:"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 337 at r4 (raw file):
{% include copy-clipboard.html %} ~~~ shell $ kubectl apply -f app-deployment.yaml
Is there an expected response?
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 342 at r4 (raw file):
## Step 12: Verify the Kubernetes deployment {% include copy-clipboard.html %}
Add some intro: "On your local workstation's terminal:"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 344 at r4 (raw file):
{% include copy-clipboard.html %} ~~~ shell $ kubectl get pods
Is there an expected response for all of these?
|
From Jesse: Also talk about monitoring |
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 38 at r4 (raw file):
~~~ The CIDR notation is constructed from an IP address (e.g., `192.168.15.161`), a slash (`/`), and a number (e.g., `32`). The number is the count of leading 1-bits in the network identifier. For the example above, the IP address is 32-bits and the number is `32`, so the full IP address is also the network identifier. For more information see Digital Ocean's [Understanding IP Addresses, Subnets,and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation).
You might want to change the (e.g., 192...) since that's external IP, as we now know ;)
To find your (external) IP4, you can use curl -4 ifconfig.co. We should add this here / elsewhere.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 133 at r4 (raw file):
{% include copy-clipboard.html %} ~~~ shell $ cockroach sql --url 'postgres://maxroach@<region>.<cluster_name>:26257/defaultdb?sslmode=verify-full&sslrootcert=<certs_dir>/<ca.crt>'
The SQL shell asks for a password. Suggestion: add the maxroach password here so it's easy to find, like "2. Enter the password you created for maxroach (Q7gc8rEdS):"
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 136 at r4 (raw file):
~~~ 2. Create a database `todos`:
The numbering for these steps is off (but it renders ok)
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 176 at r4 (raw file):
3. Select a **Region** to connect to. 4. From the **Database** dropdown, select `todos`. 5. On the **Connect Your App** tab, click **Copy connection string**.
I recommend putting a note here that says to save this connection string somewhere to copy and paste later so they don't have to go hunt for it again.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 184 at r4 (raw file):
1. In a new tab, install SQLAlchemy: To install SQLAlchemy, as well as a [CockroachDB Python package](https://github.com/cockroachdb/cockroachdb-python) that accounts for some differences between CockroachDB and PostgreSQL, run the following command:
Maybe change to "run the following command in a new terminal window" since the SQL shell is still open in one terminal window
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 217 at r4 (raw file):
You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/en/latest/core/engines.html?highlight=create_engine#sqlalchemy.create_engine) to make sure the [`cockroachdb`](https://github.com/cockroachdb/cockroachdb-python") dialect is used. Using the `postgres://` URL prefix to connect to your CockroachDB cluster will not work. {{site.data.alerts.end}}
Add a "Save file" step
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 267 at r4 (raw file):
~~~ shell $ docker image ls ~~~
Maybe include the expected response:
REPOSITORY TAG IMAGE ID CREATED SIZE
appdocker latest 30aaf5819cda 3 seconds ago 299MB
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 280 at r4 (raw file):
Previously, lhirata wrote…
Do you need to save this file in a specific location?
Add that you need to save it in the flask-sqlalchemy folder
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 337 at r4 (raw file):
Previously, lhirata wrote…
Is there an expected response?
I'm getting stuck here. This is what I'm getting:
kubectl apply -f app-deployment.yaml
service/appdeploy created
error: unable to recognize "app-deployment.yaml": no matches for kind "Deployment" in version "apps/v1"
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 211 at r4 (raw file):
{% include copy-clipboard.html %} ~~~ SQLALCHEMY_DATABASE_URI = 'cockroachdb://maxroach:Q7gc8rEdS@<region>.<cluster_name>:26257/todos?sslmode=verify-full&sslrootcert=<absolute path to CA certificate>'
When I copy the URI from the UI, it has postgres:// ... instead of cockroachdb:// which is confusing to have to change every time.
| {{site.data.alerts.callout_info}} | ||
| You must use the `cockroachdb://` prefix in the URL passed to [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/en/latest/core/engines.html?highlight=create_engine#sqlalchemy.create_engine) to make sure the [`cockroachdb`](https://github.com/cockroachdb/cockroachdb-python") dialect is used. Using the `postgres://` URL prefix to connect to your CockroachDB cluster will not work. | ||
| {{site.data.alerts.end}} | ||
|
|
There was a problem hiding this comment.
Add a "Test application locally" section
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ shell | ||
| $ pip install sqlalchemy cockroachdb |
There was a problem hiding this comment.
pip install sqlalchemy cockroachdb > pip install flask sqlalchemy cockroachdb
There was a problem hiding this comment.
Also maybe pip install -U Flask-SQLAlchemy (Check!)
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 217 at r4 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
Add a "Test application locally" section
Add 0.0.0.0 to:
if __name__ == '__main__':
app.run('0.0.0.0')
(in hello.py)
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 8 at r4 (raw file):
Previously, lhirata wrote…
Add a space after SQLAlchemy
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 38 at r4 (raw file):
Previously, lhirata wrote…
You might want to change the (e.g., 192...) since that's external IP, as we now know ;)
To find your (external) IP4, you can use
curl -4 ifconfig.co. We should add this here / elsewhere.
It already says "public IPv4 address" 🤦♀️
Joe's new feature will automatically pick up the IP address, so I am gonna wait till that feature lands.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 81 at r4 (raw file):
Previously, lhirata wrote…
I might add that they should save this somewhere for later so they don't have to come back later. Since they're following this tutorial, it'll get lost as soon as they click the next "Copy to clipboard" button.
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 133 at r4 (raw file):
Previously, lhirata wrote…
The SQL shell asks for a password. Suggestion: add the maxroach password here so it's easy to find, like "2. Enter the password you created for
maxroach(Q7gc8rEdS):"
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 136 at r4 (raw file):
Previously, lhirata wrote…
The numbering for these steps is off (but it renders ok)
Fixed.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 140 at r4 (raw file):
Previously, lhirata wrote…
Format:
CREATE DATABASE todos;
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 155 at r4 (raw file):
Previously, lhirata wrote…
I think these lines should all be indented
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 171 at r4 (raw file):
Previously, lhirata wrote…
This image shows the "Connect from Shell" tab, not the "Connect Your App" tab.
To-Do
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 176 at r4 (raw file):
Previously, lhirata wrote…
I recommend putting a note here that says to save this connection string somewhere to copy and paste later so they don't have to go hunt for it again.
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 182 at r4 (raw file):
Previously, lhirata wrote…
Change to: "In a new terminal tab"
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 184 at r4 (raw file):
Previously, lhirata wrote…
Maybe change to "run the following command in a new terminal window" since the SQL shell is still open in one terminal window
We already said "in a new terminal window" 🤔
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 207 at r4 (raw file):
Previously, lhirata wrote…
"Step 5" is a little confusing since there are multiple Step 5s and a section called Step 5. Maybe say "generated in Step 5. Generate the application connection string" and add a link?
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 211 at r4 (raw file):
Previously, lhirata wrote…
When I copy the URI from the UI, it has
postgres:// ...instead ofcockroachdb://which is confusing to have to change every time.
I know!!! UX bug :(
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 217 at r4 (raw file):
Previously, lhirata wrote…
Add a "Save file" step
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 217 at r4 (raw file):
Previously, lhirata wrote…
Add
0.0.0.0to:if __name__ == '__main__': app.run('0.0.0.0')(in hello.py)
Need to update the example code. Made a note of it.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 220 at r4 (raw file):
Previously, lhirata wrote…
Add some intro: "On your local workstation's terminal:"
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 227 at r4 (raw file):
Previously, lhirata wrote…
I would also link to Step 6 here and maybe include the rest of the section title
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 267 at r4 (raw file):
Previously, lhirata wrote…
Maybe include the expected response:
REPOSITORY TAG IMAGE ID CREATED SIZE appdocker latest 30aaf5819cda 3 seconds ago 299MB
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 271 at r4 (raw file):
Previously, lhirata wrote…
I would also link to Step 3 here and maybe include the rest of the section title
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 280 at r4 (raw file):
Previously, lhirata wrote…
Add that you need to save it in the flask-sqlalchemy folder
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 335 at r4 (raw file):
Previously, lhirata wrote…
Add some intro: "On your local workstation's terminal:"
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 342 at r4 (raw file):
Previously, lhirata wrote…
Add some intro: "On your local workstation's terminal:"
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 344 at r4 (raw file):
Previously, lhirata wrote…
Is there an expected response for all of these?
Done.
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 222 at r4 (raw file):
{% include copy-clipboard.html %} ~~~ shell $ minikube start
Maybe we should add a note that this could take a minute to start.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 227 at r4 (raw file):
Previously, lhirata wrote…
I would also link to Step 6 here and maybe include the rest of the section title
This should also be "In the flask-sqlalchemy folder you created", not flask-python
Amruta-Ranade
force-pushed
the
MSO_tutorials
branch
from
88f63d6 to
48ffa21
Compare
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-build-a-python-app-with-kubernetes.md, line 210 at r6 (raw file):
~~~ 4. 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.
Here's where we need to tell them to replace <password> with Q7gc8rEdS and <certs_dir> with the /data/certs/<CA certificate>. You might want to explain that we're pointing to where the CA certificate will be stored as a secret within the Kubernetes cluster.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 221 at r6 (raw file):
{{site.data.alerts.end}} ### Step 7. Test the application locally:
Remove the colon.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 320 at r6 (raw file):
~~~ ### Step 11. Create the deployment
Let's rename this Step 11. Run the app, since that's the end goal here, not just creating the deployment configs.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 418 at r6 (raw file):
~~~ The application will open in the browser.
Here's where we need to add a bit more info in case users run into the same problem as me:
The application will open in the browser. If you get a `refused to connect` message, use port-forwarding to reach the application:
1. Get the name of one of the pods:
~~~ shell
$ kubectl get pods
~~~
~~~
NAME READY STATUS RESTARTS AGE
appdeploy-577f66b4c8-46s5r 0/1 ErrImageNeverPull 0 23m
appdeploy-577f66b4c8-9chjx 0/1 ErrImageNeverPull 0 23m
appdeploy-577f66b4c8-cnhrg 0/1 ErrImageNeverPull 0 23m
~~~
2. Port-forward from your local machine to one of the pods:
~~~ shell
$ kubectl port-forward appdeploy-5f5868f6bf-2cjt5 5000:5000
~~~
~~~
Forwarding from 127.0.0.1:5000 -> 5000
Forwarding from [::1]:5000 -> 5000
~~~
3. Go to `http://localhost:5000/` in your browser.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 182 at r4 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
I actually think
In a new terminalis sufficient, and it's what we use throughout most other tutorials.
Step 1 is actually only relevant for testing the application locally, so please make it the first substep under Step 7. Test the application locally.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 13 at r5 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
Done.
The formatting is wrong. Instead of [minikube][documentation], you need [minikube].
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 15 at r5 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
I am not sure..I followed the minikube-CockroachDB setup while experimenting with MSO-minikube, so retained all related info.
Confirmed with Joel. You can completed remove this note.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 17 at r5 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
Done.
I still find these h2 headings overly verbose. I'd go with Prepare your cluster, Build the app, and Deploy the app. The rest of the context is clear in the page title and intro.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 77 at r5 (raw file):
In step 6, you still need to remove this:
and move the
ca.crtfile to thecertsdirectory
In step 8, you need to put backticks around ca.cert and certs.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 179 at r5 (raw file):
As discussed offline, absolute path to your certs directory isn't right, since we'll need to point to the path within the contain, not on the host. So let's cut it down to just this:
Copy the application connection string to an accessible location. You will update the password and certificate path in the next step.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 377 at r5 (raw file):
This is now repetitive. Let's just remove:
Run the following
kubectlcommand:
Place a colon after:
- Create the deployment with
kubectl:
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 391 at r5 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
Done.
Add a colon after deployment and remove Run the following kubectl commands.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 419 at r5 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
But it should start automatically 🤔
My point here is that the steps above are about creating the deployment but the app isn't actually running until you run the next command. I really think you need to make this:
5. Start the app:
~~~
$ minikube service appdeploy
~~~
|
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 234 at r5 (raw file):
@DuskEagle, does that sound ok? |
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-build-a-python-app-with-kubernetes.md, line 221 at r6 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Remove the colon.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 320 at r6 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Let's rename this
Step 11. Run the app, since that's the end goal here, not just creating the deployment configs.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 418 at r6 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Here's where we need to add a bit more info in case users run into the same problem as me:
The application will open in the browser. If you get a `refused to connect` message, use port-forwarding to reach the application: 1. Get the name of one of the pods: ~~~ shell $ kubectl get pods ~~~ ~~~ NAME READY STATUS RESTARTS AGE appdeploy-577f66b4c8-46s5r 0/1 ErrImageNeverPull 0 23m appdeploy-577f66b4c8-9chjx 0/1 ErrImageNeverPull 0 23m appdeploy-577f66b4c8-cnhrg 0/1 ErrImageNeverPull 0 23m ~~~ 2. Port-forward from your local machine to one of the pods: ~~~ shell $ kubectl port-forward appdeploy-5f5868f6bf-2cjt5 5000:5000 ~~~ ~~~ Forwarding from 127.0.0.1:5000 -> 5000 Forwarding from [::1]:5000 -> 5000 ~~~ 3. Go to `http://localhost:5000/` in your browser.
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 171 at r4 (raw file):
Previously, Amruta-Ranade (Amruta Ranade) wrote…
To-Do
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 200 at r4 (raw file):
Previously, lhirata wrote…
Suggested change to: "Navigate to the
falst-alchemydirectory:"
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 222 at r4 (raw file):
Previously, lhirata wrote…
Maybe we should add a note that this could take a minute to start.
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 15 at r5 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Confirmed with Joel. You can completed remove this note.
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 179 at r5 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
As discussed offline,
absolute path to your certs directoryisn't right, since we'll need to point to the path within the contain, not on the host. So let's cut it down to just this:Copy the application connection string to an accessible location. You will update the password and certificate path in the next step.
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 234 at r5 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Also, I think we may want to add a note here along the following lines:
These steps focus on deploying your app locally. For production Kubernetes deployments, use a service like GKE.
@DuskEagle, does that sound ok?
Done.
v19.1/managed-orchestrate-a-python-app-using-kubernetes.md, line 419 at r5 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
My point here is that the steps above are about creating the deployment but the app isn't actually running until you run the next command. I really think you need to make this:
5. Start the app: ~~~ $ minikube service appdeploy ~~~
Done.
|
Not ready for a final review yet..still working on the monitoring section. |
| build_for: [managed] | ||
| --- | ||
|
|
||
| This tutorial shows you how to run a [sample Python To-Do app](https://github.com/cockroachdb/examples-python/tree/master/flask-sqlalchemy) on a Managed CockroachDB cluster using the [Kubernetes](http://kubernetes.io/) orchestration system. |
There was a problem hiding this comment.
would be good to say up front something like
"in this tutorial, your app will be running on a local kubernetes cluster via minikube. Similar steps can be used to deploy it on a non-local k8s cluster, such as GKE, EKS, RedHat, etc"
|
To-do:
|
|
@piyush-singh Please review the monitoring section. |
There was a problem hiding this comment.
Reviewed 1 of 4 files at r3, 1 of 5 files at r4, 1 of 3 files at r6, 1 of 2 files at r7, 1 of 1 files at r9.
Reviewable status:
v19.1/managed-build-a-python-app-with-kubernetes.md, line 473 at r9 (raw file):
You can also access the Admin UI by navigating to `https://<cluster-name>crdb.io:8080/#/metrics/overview/cluster`. Replace the `<cluster-name>` placeholder with the name of your cluster. 2. In the **Username** field, enter `maxroach`.
We could make this more generally applicable by explaining that any SQL user will work, but okay to leave this in too.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 482 at r9 (raw file):
- Number of live, dead, and suspect nodes - Number of unavailable ranges
Ideally, managed clusters would never have unavailable ranges since, but okay to include this for now (maybe swap for under-replicated?).
v19.1/managed-build-a-python-app-with-kubernetes.md, line 484 at r9 (raw file):
- Number of unavailable ranges - Queries per second - Service latency across the cluster.
One random thought - could use the network diagnostics matrix to see inter-node latencies.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 491 at r9 (raw file):
2. On the [**Hardware** dashboard](https://www.cockroachlabs.com/docs/stable/admin-ui-hardware-dashboard.html), view metrics about CPU usage, disk throughput, network traffic, storage capacity, and memory. #### Monitor runtime usage
I would actually just omit this section - the CPU time graph is hard to interpret, and the Memory usage differs from the hardware metrics page in hard to explain ways.
Amruta-Ranade
changed the title
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-build-a-python-app-with-kubernetes.md, line 494 at r10 (raw file):
1. Click the gear icon on the left-hand navigation bar. 2. In the **Reports** section, click **Network Latency** to check latencies between all nodes in your cluster.
Nice substitution! This will be very handy
|
Monitoring section LGTM |
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-build-a-python-app-with-kubernetes.md, line 192 at r10 (raw file):
~~~ 2. Navigate to the flask-alchemy folder:
Put backticks around flask-alchemy.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 214 at r10 (raw file):
This is a little redundant. I'd just go with:
- Install SQLAlchemy, as well as a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL:
v19.1/managed-build-a-python-app-with-kubernetes.md, line 259 at r10 (raw file):
### Step 9. Create a Kubernetes secret Create a Kubernetes secret to store the CA certificate you downloaded in [Step 3. Generate the CockroachDB client connection string](#step-3-generate-the-cockroachdb-client-connection-string):
I don't think it's necessary to link back to step 3. You can just say you downloaded earlier.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 294 at r10 (raw file):
### Step 11. Dockerize your application 1. In the `flask-sqlalchemy` folder you created in [Step 6. Configure the sample Python app](#step-6-configure-the-sample-python-app), create a file named `Dockerfile` and copy the following code into the file:
I think you can remove you created in Step 6.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 441 at r10 (raw file):
1. Get the name of one of the pods: ~~~ shell
Add copy-to-clipboard.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 454 at r10 (raw file):
2. Port-forward from your local machine to one of the pods: ~~~ shell
Add copy-to-clipboard.
There was a problem hiding this comment.
Reviewable status:
v19.1/managed-orchestrate-an-app-using-kubernetes.md, line 28 at r3 (raw file):
Previously, DuskEagle (Joel Kenny) wrote…
Again, maybe just refer to the other page instead of copying this information here. If I'm following through each of the tutorials in order seeing this information again is unnecessary.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 8 at r8 (raw file):
Previously, vilterp (Pete Vilter) wrote…
would be good to say up front something like
"in this tutorial, your app will be running on a local kubernetes cluster via minikube. Similar steps can be used to deploy it on a non-local k8s cluster, such as GKE, EKS, RedHat, etc"
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 473 at r9 (raw file):
Previously, piyush-singh (Piyush Singh) wrote…
We could make this more generally applicable by explaining that any SQL user will work, but okay to leave this in too.
We use the maxroach user throughout the tutorial, so want to keep it consistent here.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 482 at r9 (raw file):
Previously, piyush-singh (Piyush Singh) wrote…
Ideally, managed clusters would never have unavailable ranges since, but okay to include this for now (maybe swap for under-replicated?).
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 484 at r9 (raw file):
Previously, piyush-singh (Piyush Singh) wrote…
One random thought - could use the network diagnostics matrix to see inter-node latencies.
Added a "Monitor inter-node latencies" section
v19.1/managed-build-a-python-app-with-kubernetes.md, line 491 at r9 (raw file):
Previously, piyush-singh (Piyush Singh) wrote…
I would actually just omit this section - the CPU time graph is hard to interpret, and the Memory usage differs from the hardware metrics page in hard to explain ways.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 192 at r10 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Put backticks around
flask-alchemy.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 214 at r10 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
This is a little redundant. I'd just go with:
- Install SQLAlchemy, as well as a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL:
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 259 at r10 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
I don't think it's necessary to link back to step 3. You can just say
you downloaded earlier.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 294 at r10 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
I think you can remove
you created in Step 6.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 441 at r10 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Add copy-to-clipboard.
Done.
v19.1/managed-build-a-python-app-with-kubernetes.md, line 454 at r10 (raw file):
Previously, jseldess (Jesse Seldess) wrote…
Add copy-to-clipboard.
Done.
Review requests: