Skip to content

Commit 1ed789e

Browse files
kweinmeisterkweinmeister
authored
fix: update Cloud SQL service account instructions (GoogleCloudPlatform#3057)
* Fix: update Cloud SQL service account instructions * limit line length to 80 chars
1 parent 8fc8d3a commit 1ed789e

3 files changed

Lines changed: 225 additions & 132 deletions

File tree

‎cloud-sql/mysql/mysql/README.md‎

Lines changed: 88 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -2,52 +2,64 @@
22

33
## Before you begin
44

5-
1. If you haven't already, set up a Node.js Development Environment by following the [Node.js setup guide](https://cloud.google.com/nodejs/docs/setup) and
6-
[create a project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project).
7-
8-
1. Create a 2nd Gen Cloud SQL Instance by following these
9-
[instructions](https://cloud.google.com/sql/docs/mysql/create-instance). Note the instance connection name,
10-
database user, and database password that you create.
11-
12-
1. Create a database for your application by following these
13-
[instructions](https://cloud.google.com/sql/docs/mysql/create-manage-databases). Note the database
14-
name.
15-
16-
1. Create a service account with the 'Cloud SQL Client' permissions by following these
17-
[instructions](https://cloud.google.com/sql/docs/mysql/connect-external-app#4_if_required_by_your_authentication_method_create_a_service_account).
18-
Download a JSON key to use to authenticate your connection.
19-
5+
1. If you haven't already, set up a Node.js Development Environment by following
6+
the [Node.js setup guide](https://cloud.google.com/nodejs/docs/setup) and
7+
[create a
8+
project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project).
9+
10+
1. Create a 2nd Gen Cloud SQL Instance by following these
11+
[instructions](https://cloud.google.com/sql/docs/mysql/create-instance). Note
12+
the instance connection name, database user, and database password that you
13+
create.
14+
15+
1. Create a database for your application by following these
16+
[instructions](https://cloud.google.com/sql/docs/mysql/create-manage-databases).
17+
Note the database name.
18+
19+
1. Create a service account following these
20+
[instructions](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating),
21+
and then grant the `roles/cloudsql.client` role following these
22+
[instructions](https://cloud.google.com/iam/docs/granting-changing-revoking-access#grant-single-role).
23+
Download a JSON key to use to authenticate your connection.
2024

2125
1. Use the information noted in the previous steps:
26+
2227
```bash
2328
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account/key.json
2429
export INSTANCE_CONNECTION_NAME='<MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>'
2530
export DB_USER='my-db-user'
2631
export DB_PASS='my-db-pass'
2732
export DB_NAME='my_db'
2833
```
29-
Note: Defining credentials in environment variables is convenient, but not secure. For a more secure solution, use
30-
[Secret Manager](https://cloud.google.com/secret-manager/) to help keep secrets safe. You can then define
31-
`export CLOUD_SQL_CREDENTIALS_SECRET='projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION'` to reference a secret
32-
that stores your Cloud SQL database password. The sample app checks for your defined secret version. If a version is
33-
present, the app retrieves the `DB_PASS` from Secret Manager before it connects to Cloud SQL.
34+
35+
Note: Defining credentials in environment variables is convenient, but not
36+
secure. For a more secure solution, use [Secret
37+
Manager](https://cloud.google.com/secret-manager/) to help keep secrets safe.
38+
You can then define `export
39+
CLOUD_SQL_CREDENTIALS_SECRET='projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION'`
40+
to reference a secret that stores your Cloud SQL database password. The sample
41+
app checks for your defined secret version. If a version is present, the app
42+
retrieves the `DB_PASS` from Secret Manager before it connects to Cloud SQL.
3443

3544
## Running locally
3645

3746
To run this application locally, download and install the `cloud_sql_proxy` by
38-
[following the instructions](https://cloud.google.com/sql/docs/mysql/sql-proxy#install).
47+
[following the
48+
instructions](https://cloud.google.com/sql/docs/mysql/sql-proxy#install).
3949

40-
Instructions are provided below for using the proxy with a TCP connection or a Unix Domain Socket.
41-
On Linux or Mac OS you can use either option, but on Windows the proxy currently requires a TCP
42-
connection.
50+
Instructions are provided below for using the proxy with a TCP connection or a
51+
Unix Domain Socket. On Linux or Mac OS you can use either option, but on Windows
52+
the proxy currently requires a TCP connection.
4353

4454
### Launch proxy with TCP
4555

46-
To run the sample locally with a TCP connection, set environment variables and launch the proxy as
47-
shown below.
56+
To run the sample locally with a TCP connection, set environment variables and
57+
launch the proxy as shown below.
4858

4959
#### Linux / Mac OS
60+
5061
Use these terminal commands to initialize environment variables:
62+
5163
```bash
5264
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account/key.json
5365
export INSTANCE_HOST='127.0.0.1'
@@ -58,12 +70,15 @@ export DB_NAME='<DB_NAME>'
5870
```
5971

6072
Then use this command to launch the proxy in the background:
73+
6174
```bash
6275
./cloud_sql_proxy -instances=<project-id>:<region>:<instance-name>=tcp:3306 -credential_file=$GOOGLE_APPLICATION_CREDENTIALS &
6376
```
6477

6578
#### Windows/PowerShell
79+
6680
Use these PowerShell commands to initialize environment variables:
81+
6782
```powershell
6883
$env:GOOGLE_APPLICATION_CREDENTIALS="<CREDENTIALS_JSON_FILE>"
6984
$env:INSTANCE_HOST="127.0.0.1"
@@ -74,22 +89,26 @@ $env:DB_NAME="<DB_NAME>"
7489
```
7590

7691
Then use this command to launch the proxy in a separate PowerShell session:
92+
7793
```powershell
7894
Start-Process -filepath "C:\<path to proxy exe>" -ArgumentList "-instances=<project-id>:<region>:<instance-name>=tcp:3306 -credential_file=<CREDENTIALS_JSON_FILE>"
7995
```
8096

8197
### Launch proxy with Unix Domain Socket
82-
NOTE: this option is currently only supported on Linux and Mac OS. Windows users should use the
83-
[Launch proxy with TCP](#launch-proxy-with-tcp) option.
8498

85-
To use a Unix socket, you'll need to create a directory and give write access to the user running
86-
the proxy. For example:
99+
NOTE: this option is currently only supported on Linux and Mac OS. Windows users
100+
should use the [Launch proxy with TCP](#launch-proxy-with-tcp) option.
101+
102+
To use a Unix socket, you'll need to create a directory and give write access to
103+
the user running the proxy. For example:
104+
87105
```bash
88106
sudo mkdir ./cloudsql
89107
sudo chown -R $USER ./cloudsql
90108
```
91109

92110
Use these terminal commands to initialize other environment variables as well:
111+
93112
```bash
94113
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account/key.json
95114
export INSTANCE_UNIX_SOCKET='./cloudsql/<MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>'
@@ -105,96 +124,113 @@ Then use this command to launch the proxy in the background:
105124
```
106125

107126
### Testing the application
127+
108128
Next, setup install the requirements with `npm`:
129+
109130
```bash
110131
npm install
111132
```
112133

113134
Finally, start the application:
135+
114136
```bash
115137
npm start
116138
```
117139

118-
Navigate towards `http://127.0.0.1:8080` to verify your application is running correctly.
140+
Navigate towards `http://127.0.0.1:8080` to verify your application is running
141+
correctly.
119142

120143
## Google App Engine Standard
121144

122-
To run on GAE-Standard, create an App Engine project by following the setup for these
145+
To run on GAE-Standard, create an App Engine project by following the setup for
146+
these
123147
[instructions](https://cloud.google.com/appengine/docs/standard/nodejs/quickstart#before-you-begin).
124148

125-
First, update [`app.standard.yaml`](app.standard.yaml) with the correct values to pass the environment
126-
variables into the runtime.
149+
First, update [`app.standard.yaml`](app.standard.yaml) with the correct values
150+
to pass the environment variables into the runtime.
151+
152+
Next, the following command will deploy the application to your Google Cloud
153+
project:
127154

128-
Next, the following command will deploy the application to your Google Cloud project:
129155
```bash
130156
gcloud app deploy app.standard.yaml
131157
```
132158

133-
To launch your browser and view the app at https://[YOUR_PROJECT_ID].appspot.com, run the following
134-
command:
159+
To launch your browser and view the app at
160+
<https://[YOUR_PROJECT_ID>].appspot.com, run the following command:
161+
135162
```bash
136163
gcloud app browse
137164
```
138165

139166
## Deploy to Google App Engine Flexible
140167

141-
First, update [`app.flexible.yaml`](app.flexible.yaml) with the correct values to pass the environment
142-
variables into the runtime.
168+
First, update [`app.flexible.yaml`](app.flexible.yaml) with the correct values
169+
to pass the environment variables into the runtime.
170+
171+
Next, the following command will deploy the application to your Google Cloud
172+
project:
143173

144-
Next, the following command will deploy the application to your Google Cloud project:
145174
```bash
146175
gcloud app deploy app.flexible.yaml
147176
```
148177

149-
To launch your browser and view the app at https://[YOUR_PROJECT_ID].appspot.com, run the following
150-
command:
178+
To launch your browser and view the app at
179+
<https://[YOUR_PROJECT_ID>].appspot.com, run the following command:
180+
151181
```bash
152182
gcloud app browse
153183
```
154184

155185
## Deploy to Cloud Run
156186

157-
See the [Cloud Run documentation](https://cloud.google.com/sql/docs/mysql/connect-run)
158-
for more details on connecting a Cloud Run service to Cloud SQL.
187+
See the [Cloud Run
188+
documentation](https://cloud.google.com/sql/docs/mysql/connect-run) for more
189+
details on connecting a Cloud Run service to Cloud SQL.
159190

160191
1. Build the container image:
161192

162193
```sh
163194
gcloud builds submit --tag gcr.io/[YOUR_PROJECT_ID]/run-sql
164195
```
165196

166-
2. Deploy the service to Cloud Run:
197+
1. Deploy the service to Cloud Run:
167198

168199
```sh
169200
gcloud run deploy run-sql --image gcr.io/[YOUR_PROJECT_ID]/run-sql
170201
```
171202

172203
Take note of the URL output at the end of the deployment process.
173204

174-
3. Configure the service for use with Cloud Run
205+
1. Configure the service for use with Cloud Run
175206

176207
```sh
177208
gcloud run services update run-sql \
178209
--add-cloudsql-instances [INSTANCE_CONNECTION_NAME] \
179210
--set-env-vars INSTANCE_UNIX_SOCKET=[INSTANCE_UNIX_SOCKET],\
180211
DB_USER=[MY_DB_USER],DB_PASS=[MY_DB_PASS],DB_NAME=[MY_DB]
181212
```
213+
182214
Replace environment variables with the correct values for your Cloud SQL
183215
instance configuration.
184216

185217
This step can be done as part of deployment but is separated for clarity.
186218

187-
It is recommended to use the [Secret Manager integration](https://cloud.google.com/run/docs/configuring/secrets) for Cloud Run instead
188-
of using environment variables for the SQL configuration. The service injects the SQL credentials from
189-
Secret Manager at runtime via an environment variable.
219+
It is recommended to use the [Secret Manager
220+
integration](https://cloud.google.com/run/docs/configuring/secrets) for Cloud
221+
Run instead of using environment variables for the SQL configuration. The
222+
service injects the SQL credentials from Secret Manager at runtime via an
223+
environment variable.
190224

191225
Create secrets via the command line:
226+
192227
```sh
193228
echo -n $INSTANCE_UNIX_SOCKET | \
194229
gcloud secrets create [INSTANCE_UNIX_SOCKET_SECRET] --data-file=-
195230
```
196231

197232
Deploy the service to Cloud Run specifying the env var name and secret name:
233+
198234
```sh
199235
gcloud beta run deploy SERVICE --image gcr.io/[YOUR_PROJECT_ID]/run-sql \
200236
--add-cloudsql-instances $INSTANCE_CONNECTION_NAME \
@@ -204,7 +240,7 @@ gcloud beta run deploy SERVICE --image gcr.io/[YOUR_PROJECT_ID]/run-sql \
204240
DB_NAME=[DB_NAME_SECRET]:latest
205241
```
206242

207-
4. Navigate your browser to the URL noted in step 2.
243+
1. Navigate your browser to the URL noted in step 2.
208244

209-
For more details about using Cloud Run see http://cloud.run.
210-
Review other [Node.js on Cloud Run samples](../../../run/).
245+
For more details about using Cloud Run see <http://cloud.run>. Review other
246+
[Node.js on Cloud Run samples](../../../run/).

0 commit comments

Comments
 (0)