GCE and general cloud deployment improvements #574

sploiselle · 2016-08-22T20:59:31Z

Includes:

Steps for manually deploying CockroachDB on GCE
Changes structure for Cloud Deployment docs to optimize for SEO (1 page per provider) and modularity (expands TOC to include individual providers)
Stub for AWS using existing Terraform info
Provides general guidance for any cloud environment

Related issues:

Closes #509

@mberhault –– Can you review?

This change is

mberhault · 2016-08-23T13:40:10Z

lgtm

a-robinson · 2016-08-23T14:18:30Z

deploy-cockroachdb-on-google-cloud-platform.md

+
+This page shows you how to manually deploy an insecure multi-node CockroachDB cluster on Google Cloud Platform's Compute Engine.
+
+{{site.data.alerts.callout_warning}} This guide demonstrates how to deploy an <strong>insecure</strong> cluster, which we do not recommend for data in production. We'll update this page once we've improved the workflow for deploying secure clusters.{{site.data.alerts.end}}


Can you explain what plans we have for improving the workflow for deploying secure clusters? I ask since it's also relevant for deploying on top of container orchestration systems like Kubernetes.

jseldess · 2016-08-24T16:01:02Z

Nice, @spoiselle! Some overall comments here and specifics below.

I'd prefer that the tutorial read more explicitly as a sequence of steps. Would you be willing to do "Step 1. Configure your network", "Step 2. Create instances", etc.?
There's are a few links on manual-deployment.md that point to the overview cloud-deployment.md page. Do you think we should update those links to be more specific now?

Still need to review last half of the tutorial. Will do that soon.

Review status: 0 of 4 files reviewed at latest revision, 7 unresolved discussions, some commit checks failed.

cloud-deployment.md, line 16 [r2] (raw file):
Can you add these details to the Requirements section of manual-deployment.md as well? I think we'd just want to make this bullet more explicit:

Your network configuration allows the machines to talk to each other and clients to talk to the machines.

deploy-cockroachdb-on-aws.md, line 11 [r2] (raw file):

More AWS deployment docs coming soon.

## See Also

Let's add "Deploy CockroachDB on Google Cloud Platform GCE" to the See Also list as well.

deploy-cockroachdb-on-google-cloud-platform.md, line 30 [r2] (raw file):
As discussed offline, we should clarify that there's nothing you need to do for inter-node communication; it'll work by default. Also, I'm thinking it'd be possible to simplify this step somewhat, for example:

Inter-node communication works by default using your GCE instances' internal IP addresses, which allow communication with other instances on CockroachDB's default port 26257. However, you need to create firewall rules to accept data from an application external to GCE and to expose your admin UI.

To create firewall rules, see Google Cloud Platform: Adding a firewall rule.

Guidance

...

Thoughts, @sploiselle?

deploy-cockroachdb-on-google-cloud-platform.md, line 69 [r2] (raw file):

## Create Instances

[Create an instance](https://cloud.google.com/compute/docs/instances/create-start-instance) for each node you plan to have in your cluster. We typically recommend 3 or 5 to ensure survivability.

I think the important point is running at least 3. Probably don't need to state an upper limit. Also, can we find a way to link to https://www.cockroachlabs.com/docs/configure-replication-zones.html#nodereplica-recommendations?

deploy-cockroachdb-on-google-cloud-platform.md, line 73 [r2] (raw file):

{{site.data.alerts.callout_danger}} Instances you host CockroachDB on must use a persistent SSD drive (<strong><a href="https://cloud.google.com/compute/docs/instances/create-start-instance">Create Instance</a> > Boot disk > Change > Boot disk type > SSD persistent disk</strong>).{{site.data.alerts.end}}

If you used a tag for your firewall rules, include it when you create the instance (**Management, disk, networking, SSH keys > Tags**).

As discussed offline, I couldn't quite follow this guidance, so let's maybe be a little more verbose for the sake of clarify, e.g., "If you used a tag for your firewall rules, when you create the instance, select Management, disk, networking, SSH keys. Then on the Management tab, enter the tag in the Tags field.

Also, do you have to check the Allow HTTP traffic and Allow HTTPS traffic boxes?

Comments from Reviewable

jseldess · 2016-08-24T17:39:09Z

Review status: 0 of 4 files reviewed at latest revision, 14 unresolved discussions, some commit checks failed.

deploy-cockroachdb-on-google-cloud-platform.md, line 80 [r2] (raw file):

ssh @

To be consistent with the rest of the docs, let's start each command with the $ prompt. Same for all subsequent commands.

deploy-cockroachdb-on-google-cloud-platform.md, line 85 [r2] (raw file):
Let's combine these into a single code block. If you want, you could add a comment above each command, e.g.:

# Get the latest CockroachDB tarball.
$ wget https://binaries.cockroachdb.com/cockroach-{{site.data.strings.version}}.linux-amd64.tgz

# Extract the binary.
$ tar -xf cockroach-{{site.data.strings.version}}.linux-amd64.tgz  \
> --strip=1 cockroach-{{site.data.strings.version}}.linux-amd64/cockroach

# Move the binary.
$ sudo mv cockroach /usr/local/bin

deploy-cockroachdb-on-google-cloud-platform.md, line 114 [r2] (raw file):

2.    Install CockroachDB from our latest binary:

  ~~~ shell

Same as above: combine into single code block.

deploy-cockroachdb-on-google-cloud-platform.md, line 147 [r2] (raw file):

2.    Launch the built-in SQL client and create a database:

Same as above: combine into single code block.

deploy-cockroachdb-on-google-cloud-platform.md, line 187 [r2] (raw file):

- **Databases** to ensure `insecurenodetest` is listed alongside `system`

## Using the Database

For consistency: "Use the Database".

deploy-cockroachdb-on-google-cloud-platform.md, line 192 [r2] (raw file):

1. [Implement your data model](sql-statements.html).
2. [Create users](grant.html).

This is a little misleading, because you're not really creating users when granting permissions. We don't really have "user" entities right now. So let's go with something like "Grant privileges to users".

deploy-cockroachdb-on-google-cloud-platform.md, line 195 [r2] (raw file):

3. [Connect your application](install-client-drivers.html).

## See Also

Let's also link to the aws page.

Comments from Reviewable

sploiselle · 2016-08-24T21:48:33Z

Done.

Review status: 0 of 5 files reviewed at latest revision, 14 unresolved discussions.

cloud-deployment.md, line 16 [r2] (raw file):

Previously, jseldess wrote…

Can you add these details to the Requirements section of manual-deployment.md as well? I think we'd just want to make this bullet more explicit:

Your network configuration allows the machines to talk to each other and clients to talk to the machines.

Done.

deploy-cockroachdb-on-aws.md, line 11 [r2] (raw file):

Previously, jseldess wrote…

Let's add "Deploy CockroachDB on Google Cloud Platform GCE" to the See Also list as well.

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 30 [r2] (raw file):

Previously, jseldess wrote…

As discussed offline, we should clarify that there's nothing you need to do for inter-node communication; it'll work by default. Also, I'm thinking it'd be possible to simplify this step somewhat, for example:

Inter-node communication works by default using your GCE instances' internal IP addresses, which allow communication with other instances on CockroachDB's default port 26257. However, you need to create firewall rules to accept data from an application external to GCE and to expose your admin UI.

To create firewall rules, see Google Cloud Platform: Adding a firewall rule.

Guidance

...

Thoughts, @sploiselle?

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 69 [r2] (raw file):

Previously, jseldess wrote…

I think the important point is running at least 3. Probably don't need to state an upper limit. Also, can we find a way to link to https://www.cockroachlabs.com/docs/configure-replication-zones.html#nodereplica-recommendations?

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 73 [r2] (raw file):

Previously, jseldess wrote…

As discussed offline, I couldn't quite follow this guidance, so let's maybe be a little more verbose for the sake of clarify, e.g., "If you used a tag for your firewall rules, when you create the instance, select Management, disk, networking, SSH keys. Then on the Management tab, enter the tag in the Tags field.

Also, do you have to check the Allow HTTP traffic and Allow HTTPS traffic boxes?

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 80 [r2] (raw file):

Previously, jseldess wrote…

To be consistent with the rest of the docs, let's start each command with the $ prompt. Same for all subsequent commands.

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 85 [r2] (raw file):

Previously, jseldess wrote…

Let's combine these into a single code block. If you want, you could add a comment above each command, e.g.:

# Get the latest CockroachDB tarball.
$ wget https://binaries.cockroachdb.com/cockroach-{{site.data.strings.version}}.linux-amd64.tgz

# Extract the binary.
$ tar -xf cockroach-{{site.data.strings.version}}.linux-amd64.tgz  \
> --strip=1 cockroach-{{site.data.strings.version}}.linux-amd64/cockroach

# Move the binary.
$ sudo mv cockroach /usr/local/bin

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 114 [r2] (raw file):

Previously, jseldess wrote…

Same as above: combine into single code block.

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 147 [r2] (raw file):

Previously, jseldess wrote…

Same as above: combine into single code block.

because one is SQL and one is shell, leaving these separate.

deploy-cockroachdb-on-google-cloud-platform.md, line 187 [r2] (raw file):

Previously, jseldess wrote…

For consistency: "Use the Database".

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 192 [r2] (raw file):

Previously, jseldess wrote…

This is a little misleading, because you're not really creating users when granting permissions. We don't really have "user" entities right now. So let's go with something like "Grant privileges to users".

Done.

deploy-cockroachdb-on-google-cloud-platform.md, line 195 [r2] (raw file):

Previously, jseldess wrote…

Let's also link to the aws page.

Done.

Comments from Reviewable

sploiselle · 2016-08-30T15:19:14Z

@jseldess Persistent disks work so I was able to remove the local scratch disk SSD requirements. Barring any further edits, this is good to merge.

jseldess · 2016-08-30T21:28:28Z

Review status: 0 of 5 files reviewed at latest revision, 14 unresolved discussions.

Comments from Reviewable

…ockroachdb#574)

sploiselle assigned mberhault Aug 22, 2016

a-robinson reviewed Aug 23, 2016
View reviewed changes

sploiselle force-pushed the gce-manual-deploy branch 2 times, most recently from ee3ccdf to 933b19d Compare August 23, 2016 20:59

sploiselle force-pushed the gce-manual-deploy branch from 933b19d to 566f39c Compare August 24, 2016 21:47

sploiselle force-pushed the gce-manual-deploy branch 4 times, most recently from 31d9f90 to a5ed69f Compare August 25, 2016 19:55

GCE and general cloud deployment improvements

7127398

sploiselle force-pushed the gce-manual-deploy branch from a5ed69f to 7127398 Compare August 30, 2016 15:09

sploiselle merged commit 3ae5889 into gh-pages Sep 8, 2016

sploiselle deleted the gce-manual-deploy branch September 8, 2016 14:51

Simran-B added a commit to Simran-B/docs that referenced this pull request Aug 21, 2025

Don't use deprecated functions NEAR() and WITHIN() in AQL tutorial (c…

c696341

…ockroachdb#574)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

GCE and general cloud deployment improvements #574

GCE and general cloud deployment improvements #574

Uh oh!

sploiselle commented Aug 22, 2016 •

edited by andreimatei

Loading

Uh oh!

mberhault commented Aug 23, 2016

Uh oh!

a-robinson Aug 23, 2016

Uh oh!

jseldess commented Aug 24, 2016

Guidance

Uh oh!

jseldess commented Aug 24, 2016

Uh oh!

sploiselle commented Aug 24, 2016

Guidance

Uh oh!

sploiselle commented Aug 30, 2016

Uh oh!

jseldess commented Aug 30, 2016

Uh oh!

Uh oh!


		This page shows you how to manually deploy an insecure multi-node CockroachDB cluster on Google Cloud Platform's Compute Engine.

		{{site.data.alerts.callout_warning}} This guide demonstrates how to deploy an <strong>insecure</strong> cluster, which we do not recommend for data in production. We'll update this page once we've improved the workflow for deploying secure clusters.{{site.data.alerts.end}}

GCE and general cloud deployment improvements #574

GCE and general cloud deployment improvements #574

Uh oh!

Conversation

sploiselle commented Aug 22, 2016 • edited by andreimatei Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Includes:

Related issues:

Uh oh!

mberhault commented Aug 23, 2016

Uh oh!

a-robinson Aug 23, 2016

Choose a reason for hiding this comment

Uh oh!

jseldess commented Aug 24, 2016

Guidance

Uh oh!

jseldess commented Aug 24, 2016

Uh oh!

sploiselle commented Aug 24, 2016

Guidance

Uh oh!

sploiselle commented Aug 30, 2016

Uh oh!

jseldess commented Aug 30, 2016

Uh oh!

Uh oh!

sploiselle commented Aug 22, 2016 •

edited by andreimatei

Loading