Merge pull request #252 from awesome-astra/wh-createdb-createtoken

full rework of the create-token and create-DB pages + screenshots
awesome-astra · Mar 8, 2023 · bccbedf · bccbedf
2 parents 18c0140 + 0544e6f
commit bccbedf
Show file tree

Hide file tree

Showing 22 changed files with 56 additions and 39 deletions.
diff --git a/docs/img/astra/astra-create-db-1.png b/docs/img/astra/astra-create-db-1.png
diff --git a/docs/img/astra/astra-create-db-2.png b/docs/img/astra/astra-create-db-2.png
diff --git a/docs/img/astra/astra-create-db-3.png b/docs/img/astra/astra-create-db-3.png
diff --git a/docs/img/astra/astra-create-token-1.png b/docs/img/astra/astra-create-token-1.png
diff --git a/docs/img/astra/astra-create-token-2.png b/docs/img/astra/astra-create-token-2.png
diff --git a/docs/img/astra/astra-create-token-3.png b/docs/img/astra/astra-create-token-3.png
diff --git a/docs/img/astra/astra-create-token-4.png b/docs/img/astra/astra-create-token-4.png
diff --git a/docs/img/astra/astra-create-token-A.png b/docs/img/astra/astra-create-token-A.png
diff --git a/docs/img/astra/astra-create-token-B.png b/docs/img/astra/astra-create-token-B.png
diff --git a/docs/img/astra/astra-create-token-C.png b/docs/img/astra/astra-create-token-C.png
diff --git a/docs/img/astra/astra-create-token-Z.png b/docs/img/astra/astra-create-token-Z.png
diff --git a/docs/img/astra/astra-create-token-alt.gif b/docs/img/astra/astra-create-token-alt.gif
diff --git a/docs/img/astra/astra-create-token.gif b/docs/img/astra/astra-create-token.gif
diff --git a/docs/img/astra/astra-login.png b/docs/img/astra/astra-login.png
diff --git a/docs/img/astra/astra-settings-1.png b/docs/img/astra/astra-settings-1.png
diff --git a/docs/img/astra/astra-settings-2.png b/docs/img/astra/astra-settings-2.png
diff --git a/docs/img/astra/astra-settings-3.png b/docs/img/astra/astra-settings-3.png
diff --git a/docs/img/astra/roles-1.png b/docs/img/astra/roles-1.png
diff --git a/docs/img/astra/roles-11.png b/docs/img/astra/roles-11.png
diff --git a/docs/img/astra/roles-2.png b/docs/img/astra/roles-2.png
diff --git a/docs/pages/astra/create-instance.md b/docs/pages/astra/create-instance.md
@@ -16,46 +16,49 @@
 
 ## C - Procedure
 
-**✅ Step 1:Click the `sign-in` button to login or register.**
+**✅ Step 1: Click the `Create Account` button to login or register.**
 
 You can use your `Github`, `Google` accounts or register with an `email`. Make sure to chose a password with a minimum of 8 characters, containing upper and lowercase letters, and at least one number and special character.
 
-> If you already have an Astra account, you can skip this step. Locate and click the "Create Database" button on the left-side navigation bar
-> of your Astra UI, and read the next step.
+> If you already have an Astra account, you can skip this step. Locate the "Create Database" button, as shown in the next step, and read on.
 
 <img src="../../../img/astra/astra-login.png" />
 
 **✅ Step 2: Complete the creation form**
 
-_As you create a new account, you will be prompted to create a database; you will see the same form if you simply
-hit the "Create database" button in your existing Astra account._
+_If you are creating a new account, you will be brought to the DB-creation form directly._
+
+Otherwise, get to the databases dashboard (by clicking on "Databases" in the left-hand navigation bar,
+expanding it if necessary), and click the "Create Database" button on the right.
 
 <img src="../../../img/astra/astra-create-db-1.png" />
 
+Take a moment to fill the form:
+
 - **ℹ️ Fields Description**
 
 | Field              | Description                                                                                                                                                                                                                       |
 | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **database name**  | It does not need to be unique, is not used to initialize a connection, and is only a label (Between 2 and 50 characters). It is recommended to have a database for each of your applications. The free tier is limited to 5 databases. |
-| **keyspace**       | It is a logical grouping of your tables (Between 2 and 48 characters). Please use lower case and `snake_case`.                                                                                                                  |
-| **Cloud Provider** | Use the one you like. Click a cloud provider logo, pick an Area in the list and finally pick a region. We recommend choosing a region that is closest to you to reduce latency. In free tier, there is very little difference.                      |
-
-- ℹ️ `Create Database` button becomes enabled only when all fields are filled in properly. Please use only lower case and no spaces for a keyspace name.
+| **database name**  | It does not need to be unique, is not used to initialize a connection, and is only a label (keep it between 2 and 50 characters). It is recommended to have a database for each of your applications. The free tier is limited to 5 databases. |
+| **keyspace**       | It is a logical grouping of your tables (keep it between 2 and 48 characters). Prefer lower case or `snake_case`, and avoid spaces.                                                                                                                  |
+| **Cloud Provider** | Choose whatever you like. Click a cloud provider logo, pick an Area in the list and finally pick a region. We recommend choosing a region that is closest to you to reduce latency. In free tier, there is very little difference.                      |
 
-- ℹ️ You will see your new database `pending` in the Dashboard. The status will change to `Active` when the database is ready, which will only take 2-3 minutes. You will also receive an email when it is ready.
+If all fields are filled properly, clicking the "Create Database" button will start the process. It should take a couple of minutes for your database to become `Active`.
 
-**✅ Step 3: Download your token**
+In the meantime, you will be brought to the "Connect" page of the database, that is being provisioned in the meantime. You can track the progression by looking at the status label at the top, next to the database's name.
 
-The database will take about a minute to inialize. Progression can be seen on the right panel  (_**Pending - Deployed to region...**, in the screenshot below_).
+**✅ Step 3: Obtain a Database Token**
 
-- Download your token file it will be useful later to use the DB.
+While the database is created, you can generate and download a [Token](/docs/pages/astra/create-token/) to later access it from your applications.
+The automatically-generated token has a "reasonable" set of permissions (limited to this database), but you can also generate a custom token to better suit your needs.
 
 <img src="../../../img/astra/astra-create-db-2.png" />
 
-**✅ Step 4: You are all set**
+To generate the token click on the "Generate Token" button. The new token can (and should!) be copied elsewhere with the clipboard-icon button and/or downloaded in JSON format for safe storage - it will not be shown anymore once you leave the dialog.
 
-When the status is changed to `Your Database is now active` you are good to go
+<img src="../../../img/astra/astra-create-db-3.png" />
 
-- Click `[Go To Database]`.
+**✅ Step 4: Ready**
 
-<img src="../../../img/astra/astra-create-db-3.png" />
+In a couple of minutes, the database will switch to `Active`. You can now interact with it,
+for example by [downloading a Secure Connect Bundle](/docs/pages/astra/download-scb/)) and start running applications that access it.
diff --git a/docs/pages/astra/create-token.md b/docs/pages/astra/create-token.md
@@ -10,7 +10,7 @@
 
 ## A - Overview
 
-As stated in the [Create Account](/docs/pages/astra/create-account/) page the security token is associated to one and only one organization and only one role.
+As stated in the [Create Account](/docs/pages/astra/create-account/) page, the security token is associated to one and only one organization and only one role.
 
 ```mermaid
   graph TD
@@ -22,19 +22,20 @@ As stated in the [Create Account](/docs/pages/astra/create-account/) page the se
     ROLE-->|1..n|PERMISSIONS(permissions)
 ```
 
-There are a set of predefined roles within an organization which are associated with some default permissions. The full list of permissions and roles is available in [Astra Documentation](https://docs.datastax.com/en/astra/docs/user-permissions.html)
+There are a set of predefined roles within an organization which are associated with some default permissions. The full list of permissions and roles is available in the [Astra Documentation](https://docs.datastax.com/en/astra/docs/user-permissions.html).
 
 <center>
 <img src="../../../img/astra/roles-1.png" />
 <br/><i>Figure 1: Default Roles</i>
 
 <p>
 <img src="../../../img/astra/roles-11.png" />
-<br/><i>Figure 2: Permissions for a role here `Database Administrator`</i>
+<br/><i>Figure 2: Permissions for a selected role (here, "Database Administrator")</i>
 </p>
 </center>
 
-It is also possible to create custom roles and associate fined grained permissions. (`Organizations Settings / Role Managennt`)
+It is possible to manually create custom roles and tune the corresponding permissions in a fine-grained fashion (`Settings / Role Management`), to later create tokens based on them.
+For example, each time [a database is created](/docs/pages/astra/create-instance/), it comes with an autogenerated brand-new token, backed by an ad-hoc custom role essentially scoped to that database only.
 
 <center>
 <img src="../../../img/astra/roles-2.png" />
@@ -49,36 +50,49 @@ It is also possible to create custom roles and associate fined grained permissio
 
 ## C - Procedure
 
-??? note "1️⃣ Open the Organization settings panel"
+_Note that a token, albeit with a fixed set of permissions, is generated_
+_automatically for you as [a database is created](/docs/pages/astra/create-instance/). In many cases, however, you need_
+_to manually issue tokens, and here is explained how to do that._
 
-    On the top left hand corner locate the panel `Current Organization` with your email address. Use the chevron down **&#8964;** to open the menu and pick `Organization Settings`
+1️⃣ First go to the Organization settings panel in one of the following ways:
 
-    <img src="../../../img/astra/astra-create-token-1.png" />
+??? note "Settings page"
 
-??? note "2️⃣ Open the token management page"
+    On the bottom-right corner of the Astra UI, in the navigation bar, click on "Settings" next to the cog icon. (The navigation bar might be collapsed to the left). Then, select the "Token management" entry in the Settings menu.
 
-    On the new page, select `Token Management` in the menu. Then use the `Select Roles` combo to select the `Organization Administrator` role. This is the administrator of your tenant with all permissions.
+    <img src="../../../img/astra/astra-settings-1.png" />
 
-    <img src="../../../img/astra/astra-create-token-2.png" />
+??? note "From a database"
 
-    ??? tip "The same page can be accessed from the dashboard"
+    Click on the "..." next to a database in the main DB dashboard, then select "Generate a Token".
 
-        You can reach the Token Management page directly from the ellipsis menu next to your database in the main Astra dashboard. Expand to see how
+    <img src="../../../img/astra/astra-settings-2.png" />
 
-        <img src="../../../img/astra/astra-create-token-alt.gif" />
+??? note "From the Connect tab"
 
-??? note "3️⃣ Save the token as a CSV."
+    On the Connect tab of your database, click on the "create a custom token" link in the Quickstart section.
 
-    The values of `clientSecret` and `token` will not be shown to you later for security reasons. Do not share those values and never commit them on github.
+    <img src="../../../img/astra/astra-settings-3.png" />
 
-    <img src="../../../img/astra/astra-create-token-3.png" />
+2️⃣ Pick the desired role for the token in the drop-down list and click "Generate".
 
-???+ note "4️⃣ Walkthrough."
+<img src="../../../img/astra/astra-create-token-A.png" />
 
-    <img src="../../../img/astra/astra-create-token.gif" />
+3️⃣ A new token is generated for you. Make sure to copy/download the values before leaving the page, since the secrets will not be shown anymore. You can copy the individual secrets with the button next to the text fields, or directly download the whole token as a file and store it safely.
 
-??? tip "Copy values in the clipboard"
+<img src="../../../img/astra/astra-create-token-B.png" />
 
-    You can use the clipboard icons next to each parameter to copy and paste them elsewhere.
+??? tip "Anatomy of a Token"
 
-    <img src="../../../img/astra/astra-create-token-4.png" />
+    The Token is in fact three separate strings: a _Client ID_, a _Client Secret_ and
+    the _token proper_.
+    You will need some of these strings to access the database, depending on the type of access you plan.
+    Although the Client ID, strictly speaking, is not a secret, you should
+    regard this whole object as a secret and make sure not to share it inadvertently (e.g. committing
+    it to a Git repository) as it grants access to your databases.
+
+    <img src="../../../img/astra/astra-create-token-Z.png" />
+
+4️⃣ The token will not expire, unless you decide to revoke (i.e. delete) it, for example in case it is compromised. To do so, in the "Token Management" page, click on the "..." menu next to the token you want to delete.
+
+<img src="../../../img/astra/astra-create-token-C.png" />