Postgres edits

docs/quickstart/access-control/postgres.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 2
-title: Fine-Grained PostgreSQL Access
+title: Just-in-time PostgreSQL access
 image: /img/quick-tutorials/aws-iam-eks/social.png
 ---
 
@@ -24,31 +24,27 @@ export const Terminal = ({children}) => (
 );
 
 
-Otterize Simplifies PostgreSQL Least Privilege Service Access
-
 # Overview
 This tutorial will deploy an example cluster to highlight Otterize's PostgreSQL capabilities. Within that cluster is a client service that hits an endpoint on a server, which then connects to a database. The server runs two different database operations:
 1. An `INSERT` operation to append a table within the database
 2. A `SELECT` operation to validate the updates.
 
-But there’s a problem: the server can’t access the database. Luckily, with Otterize Cloud, we can create credentials, define table access, and scope it for our server’s needs.
-
-By the end of the tutorial, we will define our server-to-database authorization using Intent-Based Access Control (IBAC), and Otterize Cloud will update our server’s unique database credentials to reflect those intents.
+The server needs appropriate permissions to access the database. You could use one admin user for all services, which is insecure and is the cause for many security breaches. With Otterize, you can specify required access, and have Otterize create users and perform correctly scoped SQL GRANTs just in time, as the service spins up and down.
 
 In this tutorial, we will:
 * Deploy an example cluster
 * Make our database accessible to Otterize Cloud
-* Integrate the cluster and our database to Otterize Cloud
-* Declare our intent, ensuring our server has the right-sized access to the required tables.
+* Connect our cluster and database to Otterize Cloud
+* Declare a ClientIntents resource for the server, specifying required access
+* See that the required access has been granted
 
 # Prerequisites
 
-1. **[MiniKube](https://minikube.sigs.k8s.io/docs/start/)** - We will be running our cluster locally.
+1. **[Minikube](https://minikube.sigs.k8s.io/docs/start/)** - We will be running our cluster locally.
 ```shell
 minikube start
 ```
-2. **ngrok** - We will be using it to create a proxy to connect our database to Otterize Cloud. Once you have [ngrok account](https://dashboard.ngrok.com/signup). , you’ll want to install it in your terminal using the instructions found here: [ngrok install](https://ngrok.com/download)
-3. We will also be using [kubectl](https://kubernetes.io/docs/tasks/tools/) and [Helm](https://helm.sh/docs/intro/install/#through-package-managers)
+2. **ngrok** - We will be using it to create a proxy to connect our locally running database to Otterize Cloud, for the tutorial's purposes. Once you have an [ngrok account](https://dashboard.ngrok.com/signup), you’ll want to install it in your terminal using the instructions found here: [ngrok install](https://ngrok.com/download)
 
 # Tutorial
 
@@ -63,9 +59,9 @@ kubectl apply -n otterize-tutorial-postgres -f ${ABSOLUTE_URL}/code-examples/pos
 
 ### Make the database accessible to Otterize Cloud
 
-We need to allow Otterize Cloud to access the database server so we can set up the appropriate credentials for our server’s access. This tutorial will expose our database port to our local environment and then proxying it to Otterize Cloud using ngrok. We will need both of these processes up and running during the rest of this tutorial.
+We need to allow Otterize Cloud to access the database server so Otterize Cloud can configure on-demand credentials for our server’s access. This tutorial will expose our database port to our local environment and then proxy it to Otterize Cloud using ngrok. We will need both of these processes up and running during the rest of this tutorial.
 
-In a new terminal window, run the following command to forward our database port from our cluster into our local environment
+In a new terminal window, run the following command to forward our database port from our cluster into your local environment:
 ```shell
 kubectl port-forward svc/database 5432:5432 -n otterize-tutorial-postgres
 ```
@@ -89,7 +85,7 @@ To add the database, we head over to the [Integrations page](https://app.otteriz
 4. Leave the database type set to *PostgreSQL*
 5. Copy your *Forwarding* host and port from ngrok in the *Address* Field. This will look something like `0.tcp.us-cal-1.ngrok.io:14192`. Be sure to remove the `tcp://` portion of the URL.
 6. *Username*: otterize-tutorial, *Password*: jeffdog523
-1. Note this is a superuser, which allows Otterize to create unique credentials for each service. For production purposes, it is recommended to create a unique superuser for Otterize’s exclusive use.
+1. Note this is a superuser, which allows Otterize to create unique credentials for each service. For production, it is recommended to create a privileged user for Otterize’s exclusive use. This user should have the necessary permissions to GRANT access to any databases and tables you want it to manage.
 7. Hit *Test Connection*, and you should see an “OK” status.
 8. Hit the Add button to complete the integration
 
@@ -98,13 +94,10 @@ Create a Kubernetes cluster on the [Clusters page](https://app.otterize.com/clus
 
 After providing a cluster name and environment. For this tutorial, choose:
 
-1. mTLS and Kafka Support: Otterize Cloud
-2. Enforcement Mode: Enabled.
-3. Copy and run the unique cluster installation shell commands, but you’ll need to enable the Database Reconciler by appending the following flag to the *heml upgrade* command
-```shell
---set intentsOperator.operator.enableDatabaseReconciler=true
-```
-4. You should see the Verification Status change.
+1. mTLS and Kafka Support: None
+2. Enforcement mode: Enabled.
+3. Copy and run the Helm upgrade command.
+4. You should see the Connection status change.
 
 ### View logs for the server
 After the client, server, and database are up and running, we can see that the server does not have the appropriate access to the database by inspecting the logs with the following command.
@@ -114,16 +107,18 @@ kubectl logs -f -n otterize-tutorial-postgres deploy/server
 ```
 
 
-Example Log:
+Example log:
 <Terminal>
     pq: password authentication failed for user "svc_9cigb2qemv_otterize_tutorial_postgres_server"
 </Terminal>
 
-### Define our access intents
+### Define your ClientIntents
 
 ClientIntents are Otterize’s way of defining access through unique relationships, which lead to perfectly scoped access. In this example, we provide our `server` service the ability to insert select records to allow it to access the database.
 
-Below is our intents.yaml file. As you can see, it is scoped to our database named `otterize-tutorial` and our `public.example` table. We also have limited this access table to just `SELECT` and `INSERT` operations. We could add more databases, tables, or operations if our service required more access.
+Below is our `intents.yaml` file. As you can see, it is scoped to our database named `otterize-tutorial` and our `public.example` table. We also have limited the access to just `SELECT` and `INSERT` operations. We could add more databases, tables, or operations if our service required more access.
+
+Specifying the table and operations is optional. If you don't specify the table, access will be granted to all tables in the specified database. If you don't specify the operations, all operations will be allowed.
 ```yaml
 apiVersion: k8s.otterize.com/v1alpha3
 kind: ClientIntents
@@ -144,23 +139,24 @@ spec:
             - INSERT
 ```
 
-We can now apply our intents. Behind the scenes, Otterize Cloud creates the appropriate user and access, making our `SELECT` and `INSERT` errors disappear.
+We can now apply our intents. Behind the scenes, Otterize Cloud runs `CREATE USER` and `GRANT` queries on the database, making our `SELECT` and `INSERT` errors disappear.
 
 ```shell
 kubectl apply -f intents.yaml
 ```
 
-Example Log:
+Example log:
 <Terminal>
     Successfully INSERTED into our table
     Successfully SELECTED, most recent value:  2024-01-22T18:48:43Z
 </Terminal>
 
 That’s it! If your service’s functionality changes, adding or removing access is as simple as updating your ClientIntents definitions. For fun, try altering the `operations` to just `SELECT` or `INSERT`.
+
 # Teardown
 To remove the deployed examples, run:
 ```shell
 kubectl delete namespace otterize-tutorial-postgres
 ```
 
-End the ngrok and port forwarding processes by closing the terminal windows or cntl-c the processes.
+End the ngrok and port forwarding processes by closing the terminal windows or Ctrl-C the processes.