docs: update sidebar structure (#203)

raystack · Jul 6, 2022 · 042986c · 042986c
1 parent 44fcd43
commit 042986c
Show file tree

Hide file tree

Showing 17 changed files with 161 additions and 154 deletions.
diff --git a/docs/docs/guides/overview.md → docs/docs/concepts/overview.md b/docs/docs/guides/overview.md → docs/docs/concepts/overview.md
diff --git a/docs/docs/guides/approve-reject-appeal.md b/docs/docs/guides/approve-reject-appeal.md
@@ -1,7 +1,7 @@
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Approve/Reject Appeal
+# Manage appeal
 
 Note: Approve/reject still not supported from the CLI currently.
 

diff --git a/docs/docs/guides/complex-use-case.md b/docs/docs/guides/complex-use-case.md
@@ -1,7 +1,9 @@
-# More Complex Use Case Example
-In this example we will explain some more details around the policy configuartions. Guardian can connect to an external identity manager to retrieve user details information. When a user creates an appeal using the policy given below, Guardian will connect to **`http://youridentitymanager.com/api/users/{user_id}`** for taking the user information defined in the **`iam_schema`** within the policy. 
+# Update policy rules
+
+In this example we will explain some more details around the policy configuartions. Guardian can connect to an external identity manager to retrieve user details information. When a user creates an appeal using the policy given below, Guardian will connect to **`http://youridentitymanager.com/api/users/{user_id}`** for taking the user information defined in the **`iam_schema`** within the policy.
 
 ### Policy Example
+
 ```yaml
 id: my-second-policy
 iam:
@@ -13,19 +15,20 @@ iam:
     name: fullName
     company: companyName
 steps:
-- name: employee_check
-  description: only allow employee to access our resources
-  strategy: auto
-  approve_if: $appeal.creator.company == "Company Name"
-- name: resource_owner_approval
-  description: resource owner approval. Will skip this for playground dataset
-  strategy: manual
-  when: not ($appeal.resource.type == "dataset" && $appeal.resource.urn == "my-bq-project:playground")
-  approvers:
-  - $appeal.resource.details.owner
+  - name: employee_check
+    description: only allow employee to access our resources
+    strategy: auto
+    approve_if: $appeal.creator.company == "Company Name"
+  - name: resource_owner_approval
+    description: resource owner approval. Will skip this for playground dataset
+    strategy: manual
+    when: not ($appeal.resource.type == "dataset" && $appeal.resource.urn == "my-bq-project:playground")
+    approvers:
+      - $appeal.resource.details.owner
 ```
 
 ### Explanation
+
 For the approval, a user's appeal will follow the steps **`employee_check`** and **`resource_owner_approval`** in the same order.
 The first step is an **`auto`** strategy which checks the pre-defined condition that the employee who is requesting for the access belongs to the same company. Until then the status of the appeal will be **`pending`** for the first step(**`employee_check`**), and **`blocked`** for the second step(**`resource_owner_approval`**).
 

diff --git a/docs/docs/getting_started/configuration.md → docs/docs/guides/configuration.md b/docs/docs/getting_started/configuration.md → docs/docs/guides/configuration.md
@@ -1,14 +1,16 @@
-# Configuration
+# Configure client
 
 Guardian binary contains both the CLI client and the server itself. Each has it's own configuration in order to run. Server configuration contains information such as database credentials, log severity, etc. while CLI client configuration only has configuration about which server to connect.
 
 ## Server
 
 #### Pre-requisites
+
 - Postgres
 - Slackbot access token for notification (optional)
 
 #### Initialization
+
 Create a config.yaml file (`touch config.yaml`) in the root folder of guardian project or [use `--config` flag](#using---config-flag) to customize to config file location, or you can also [use environment variables](#using-environment-variables) to provide the server config. Setup up a database in postgres and provide the details in the DB field as given in the example below. For the purpose of this tutorial, we'll assume that the username is `your_user`, database name is `guardian`, host and port are `localhost` and `5432`.
 
 > If you're new to YAML and want to learn more, see [Learn YAML in Y minutes.](https://learnxinyminutes.com/docs/yaml/)
@@ -20,19 +22,19 @@ PORT: 3000
 LOG:
   LEVEL: info # debug|info|warning|error|fatal - default: info
 DB:
-  HOST: localhost      
+  HOST: localhost
   USER: your_user
   PASSWORD: your_password
   NAME: guardian
-  PORT: 5432          
+  PORT: 5432
 NOTIFIER:
   PROVIDER: slack
   ACCESS_TOKEN: <slack-access-token>
   ...
 AUTHENTICATED_USER_HEADER_KEY: X-Auth-Email
 JOBS:
   FETCH_RESOURCES_INTERVAL: '0 */2 * * *' # default: "0 */2 * * *" which means "At minute 0 past every 2nd hour"
-  REVOKE_EXPIRED_ACCESS_INTERVAL: '*/20 * * * *' # Default :"*/20 * * * *" which means “At every 20th minute" 
+  REVOKE_EXPIRED_ACCESS_INTERVAL: '*/20 * * * *' # Default :"*/20 * * * *" which means “At every 20th minute"
   EXPIRING_ACCESS_NOTIFICATION_INTERVAL: '0 9 * * *' # Default:"0 9 * * *" which means "At minute 0 past hour 9"
 ```
 
@@ -43,6 +45,7 @@ JOBS:
 Database migration is required during the first server initialization. In addition, re-running the migration command might be needed in a new release to apply the new schema changes (if any). It's safer to always re-run the migration script before deploying/starting a new release.
 
 To initialize the database schema, Run Migrations with the following command:
+
 ```sh
 $ guardian server migrate
 ```
@@ -71,17 +74,19 @@ All the configs can be passed as environment variables using underscore `_` as t
 PORT: 8080
 DB:
   HOST: localhost
-  USER: test 
+  USER: test
 ```
+
 Here is the corresponding environment variable for the above
 
-Configuration key | Environment variable |
-------------------|----------------------|
-PORT              | PORT                 |
-DB.HOST           | DB_HOST              |
-DB.USER           | DB_USER              |
+| Configuration key | Environment variable |
+| ----------------- | -------------------- |
+| PORT              | PORT                 |
+| DB.HOST           | DB_HOST              |
+| DB.USER           | DB_USER              |
 
 Set the env variable using export
+
 ```
 $ export PORT=8080
 ```
@@ -91,13 +96,14 @@ $ export PORT=8080
 ## CLI Client
 
 ### Initialization
+
 Guardian CLI supports CLI client to communicate with a Guardian server. To initialize the client configuration, run the following command:
 
 ```sh
 $ guardian config init
-``` 
+```
 
-A yaml file will be created in the `~/.config/odpf/guardian.yaml` directory. Open this file to configure the host for Guardian server as in the example below: 
+A yaml file will be created in the `~/.config/odpf/guardian.yaml` directory. Open this file to configure the host for Guardian server as in the example below:
 
 ```yaml
 host: "localhost:8080"

diff --git a/docs/docs/guides/create-appeal.md b/docs/docs/guides/create-appeal.md
@@ -1,6 +1,7 @@
-# Create Your First Appeal 
+# Create an appeal
 
 **Note:**
+
 1. Get the `resource_id` of Playground dataset in our example ([Steps](./update-resource#getting-the-resourceid-for-the-resource))
 2. Currently we support creating an Appeal via the API only
 
@@ -20,70 +21,67 @@ $ curl --request POST '{{HOST}}/api/v1beta1/appeals' \
   ]
 }'
 ```
+
 **Note:** Refer to the [Appeal Request](../reference/api#appeal-request-config) Configurations for more details
 
 **The Response after creating the appeal is as follows:**
 
 ```json
 {
-    "appeals": [
+  "appeals": [
+    {
+      "id": "<< appeal id >>",
+      "resource_id": "<< playground resource id >>",
+      "policy_id": "my-first-policy",
+      "policy_version": 1,
+      "status": "pending",
+      "account_id": "[email protected]",
+      "role": "viewer",
+      "resource": {
+        "id": "<< playground resource id >>",
+        "provider_type": "bigquery",
+        "provider_urn": "my-first-bigquery-provider",
+        "type": "dataset",
+        "urn": "<<my-bq-project-id>>:playground",
+        "name": "playground",
+        "details": {
+          "owner": "[email protected]"
+        },
+        "created_at": "2022-06-30T10:46:03.608245Z",
+        "updated_at": "2022-06-30T10:50:22.966110Z"
+      },
+      "approvals": [
+        {
+          "id": "<< approval id 1 >>",
+          "name": "resource_owner_approval",
+          "appeal_id": "<< appeal id >>",
+          "status": "pending",
+          "policy_id": "my-first-policy",
+          "policy_version": 1,
+          "approvers": ["[email protected]"],
+          "created_at": "2022-06-30T10:55:48.712177Z",
+          "updated_at": "2022-06-30T10:55:48.712177Z"
+        },
         {
-            "id": "<< appeal id >>",
-            "resource_id": "<< playground resource id >>",
-            "policy_id": "my-first-policy",
-            "policy_version": 1,
-            "status": "pending",
-            "account_id": "[email protected]",
-            "role": "viewer",
-            "resource": {
-                "id": "<< playground resource id >>",
-                "provider_type": "bigquery",
-                "provider_urn": "my-first-bigquery-provider",
-                "type": "dataset",
-                "urn": "<<my-bq-project-id>>:playground",
-                "name": "playground",
-                "details": {
-                    "owner": "[email protected]"
-                },
-                "created_at": "2022-06-30T10:46:03.608245Z",
-                "updated_at": "2022-06-30T10:50:22.966110Z"
-            },
-            "approvals": [
-                {
-                    "id": "<< approval id 1 >>",
-                    "name": "resource_owner_approval",
-                    "appeal_id": "<< appeal id >>",
-                    "status": "pending",
-                    "policy_id": "my-first-policy",
-                    "policy_version": 1,
-                    "approvers": [
-                        "[email protected]"
-                    ],
-                    "created_at": "2022-06-30T10:55:48.712177Z",
-                    "updated_at": "2022-06-30T10:55:48.712177Z"
-                },
-                {
-                    "id": "<< approval id 2 >>",
-                    "name": "admin_approval",
-                    "appeal_id": "<< appeal id >>",
-                    "status": "blocked",
-                    "policy_id": "my-first-policy",
-                    "policy_version": 1,
-                    "approvers": [
-                        "[email protected]"
-                    ],
-                    "created_at": "2022-06-30T10:55:48.712177Z",
-                    "updated_at": "2022-06-30T10:55:48.712177Z"
-                }
-            ],
-            "created_at": "2022-06-30T10:55:48.704006Z",
-            "updated_at": "2022-06-30T10:55:48.704006Z",
-            "revoked_at": "0001-01-01T00:00:00Z",
-            "details": {},
-            "account_type": "user",
-            "created_by": "[email protected]",
-            "creator": null
+          "id": "<< approval id 2 >>",
+          "name": "admin_approval",
+          "appeal_id": "<< appeal id >>",
+          "status": "blocked",
+          "policy_id": "my-first-policy",
+          "policy_version": 1,
+          "approvers": ["[email protected]"],
+          "created_at": "2022-06-30T10:55:48.712177Z",
+          "updated_at": "2022-06-30T10:55:48.712177Z"
         }
-    ]
+      ],
+      "created_at": "2022-06-30T10:55:48.704006Z",
+      "updated_at": "2022-06-30T10:55:48.704006Z",
+      "revoked_at": "0001-01-01T00:00:00Z",
+      "details": {},
+      "account_type": "user",
+      "created_by": "[email protected]",
+      "creator": null
+    }
+  ]
 }
-```
+```
diff --git a/docs/docs/guides/create-policy.md b/docs/docs/guides/create-policy.md
@@ -1,39 +1,41 @@
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Create Your First Policy
+# Create a policy
 
-### Pre-Requisites 
+### Pre-Requisites
 
-1. [Setting up server](../getting_started/configuration.md#starting-the-server)
-2. [Setting up the CLI](../getting_started/configuration.md#client-configuration) (if you want to create policy using CLI)
+1. [Setting up server](./configuration.md#starting-the-server)
+2. [Setting up the CLI](./configuration.md#client-configuration) (if you want to create policy using CLI)
 
 ### Example Policy
 
 ```yaml
 id: my-first-policy
 steps:
-- name: resource_owner_approval
-  description: approval from resource owner
-  strategy: manual
-  approvers:
-  - $appeal.resource.details.owner
-- name: admin_approval
-  description: approval from admin (John Doe)
-  strategy: manual
-  approvers:
-  - [email protected]
+  - name: resource_owner_approval
+    description: approval from resource owner
+    strategy: manual
+    approvers:
+      - $appeal.resource.details.owner
+  - name: admin_approval
+    description: approval from admin (John Doe)
+    strategy: manual
+    approvers:
+      - [email protected]
 ```
+
 Check [policy reference](../reference/policy.md) for more details on the policy configuration.<br/>
 
 **Explanation of this Policy example**<br/>
-When a Guardian user creates an appeal to the BigQuery resource (Playground here), this policy will applied, and the approvals required to approve that appeal are in the order as follows: <br/> 
+When a Guardian user creates an appeal to the BigQuery resource (Playground here), this policy will applied, and the approvals required to approve that appeal are in the order as follows: <br/>
+
 1. Approval from the resource owner ( this information is contained in the resource details object), and
 2. Approval from John Doe as an admin
 
 #### Policies can be created in the following ways:
 
-1. Using `guardian policy create` CLI command 
+1. Using `guardian policy create` CLI command
 2. Calling to `POST /api/v1beta1/policies` API
 
 <Tabs groupId="api">
@@ -75,4 +77,4 @@ $ curl --request POST '{{HOST}}/api/v1beta1/policies' \
   </TabItem>
 </Tabs>
 
-**Note** : For using the CLI tool, create a Policy.yaml file using the example configurations shown above and provide the path to it here.
+**Note** : For using the CLI tool, create a Policy.yaml file using the example configurations shown above and provide the path to it here.
diff --git a/docs/docs/guides/create-provider.md b/docs/docs/guides/create-provider.md
@@ -1,7 +1,7 @@
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Create BigQuery Provider
+# Create a provider
 
 We are going to register a Google Cloud Bigquery provider with a dataset named `Playground` in this example.
 

diff --git a/docs/docs/guides/introduction.md b/docs/docs/guides/introduction.md
@@ -4,7 +4,7 @@ This tour introduces you to Guardian. Along the way you will learn how to manage
 
 ### Prerequisites
 
-This tour requires you to have Guardian CLI tool installed on your local machine. You can run `guardian version` to verify the installation. Please follow [installation](../getting_started/installation) and [configuration](../getting_started/configuration) guides if you do not have it installed already.
+This tour requires you to have Guardian CLI tool installed on your local machine. You can run `guardian version` to verify the installation. Please follow [installation](../installation) and [configuration](./configuration) guides if you do not have it installed already.
 
 Guardian CLI and clients talks to Guardian server to publish and fetch policies, appeals and resources. Please make sure you also have a Guardian server running. You can also run server locally with `Guardian server start` command. For more details check deployment guide.
 

diff --git a/docs/docs/guides/update-resource.md b/docs/docs/guides/update-resource.md
@@ -1,7 +1,7 @@
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Update Resource Metadata
+# Update resource
 
 We will try to update a resource information in this example exercise. Let's say we want to add owner's information to the `playground` dataset.
 
@@ -49,10 +49,12 @@ $ guardian resource view {{resource_id}}
 ```bash
 $ curl --request GET '{{HOST}}/api/v1beta1/resources/{{resource_id}}'
 ```
+
   </TabItem>
 </Tabs>
 
 To update the resource metadata with this information add this to the resource file or request body
+
 ```yaml
 details:
   owner: [email protected]
@@ -84,4 +86,4 @@ $ curl --request PUT '{{HOST}}/api/v1beta1/resources/{{resource_id}}' \
 ```
 
   </TabItem>
-</Tabs>
+</Tabs>
diff --git a/docs/docs/getting_started/installation.md → docs/docs/installation.md b/docs/docs/getting_started/installation.md → docs/docs/installation.md