docs: update documentation (#187)

* docs: update introduction page * docs: update sidebars * docs: added installation and configuration pages * docs: updated overview * docs: updated sidebars * docs: added tour introduction page * docs: added API reference page * docs: updated appeal reference * docs: updated policy reference * docs: updated provider reference * docs: updated resource reference * docs: updated introduction * docs: updated introduction * docs: updated cli reference * docs: updated glossary * docs: updated api reference * docs: updated api reference * docs: updated api reference * docs: updated api reference * docs: updated provider * docs: updated cli reference page * docs: updated cli reference page * docs: updated cli reference page * docs: updated provider reference page * docs: updated cli reference page * docs: upgrade docusaurus and theme * docs: fix typo * docs: fix sidebar theme * docs: update roadmap section * docs: Added GCloud Provider, Moved API and CLI pages to Reference, Updated Configuration * docs: update theme styling * docs: remove package lock * docs: update sidebar styling * docs: fix tabs styling * docs: fix code font size * docs: update header position * docs: fix broken links and custom help page * doc: update readme with usage * docs: Added tutorial pages in Guides, fixed broken links * docs: Updated descriptions and response messages in API Reference * docs: Updated Guides policy example * docs: Updated Overview pages, Rm Managing pages * docs: rephrase getting started page * Update docs/docs/guides/complex-use-case.md Co-authored-by: Rahmat Hidayat <[email protected]> * Update docs/docs/getting_started/installation.md Co-authored-by: Rahmat Hidayat <[email protected]> * docs: update description in installation page Co-authored-by: Rahmat Hidayat <[email protected]> * docs: fixed installation page typo Co-authored-by: Rahmat Hidayat <[email protected]> * docs: fixed typos Co-authored-by: Rahmat Hidayat <[email protected]> * docs: fixed typos Co-authored-by: Rahmat Hidayat <[email protected]> * docs: update required info on some fields * docs: update google_bigquery to bigquery * Update provider.yml * fix: fix placeholder text * fix: fix placeholder text * docs: remove old guides * docs: remove collecting resource section Co-authored-by: Ravi Suhag <[email protected]> Co-authored-by: Rahmat Hidayat <[email protected]>
raystack · Jul 5, 2022 · 44fcd43 · 44fcd43
1 parent f0ce155
commit 44fcd43
Show file tree

Hide file tree

Showing 44 changed files with 4,923 additions and 30,862 deletions.
diff --git a/README.md b/README.md
@@ -12,11 +12,11 @@ Guardian is a on-demand access management tool. It manages resources from variou
 
 ## Key Features
 
-- **Provider Management**: Support various providers (currently only BigQuery, more coming up!) and multiple instances for each provider type
-- **Resource Management**: Resources from a provider are managed in Guardian's database. There is also an API to update resource's metadata to add additional information.
+- **Provider management**: Support various providers (currently only BigQuery, more coming up!) and multiple instances for each provider type
+- **Resource management**: Resources from a provider are managed in Guardian's database. There is also an API to update resource's metadata to add additional information.
 - **Appeal-based access**: Users are expected to create an appeal for accessing data from registered providers. The appeal will get reviewed by the configured approvers before it gives the access to the user.
 - **Configurable approval flow**: Approval flow configures what are needed for an appeal to get approved and who are eligible to approve/reject. It can be configured and linked to a provider so that every appeal created to their resources will follow the procedure in order to get approved.
-- **External Identity Manager**: This gives the flexibility to use any third-party identity manager. User properties.
+- **External identity managers**: This gives the flexibility to use any third-party identity manager. User properties.
 
 ## Documentation
 
@@ -52,52 +52,24 @@ $ guardian version
 
 ## Usage
 
-Guardian CLI is fully featured but simple to use, even for those who have very limited experience working from the command line. Run `guardian --help` to see list of all available commands and instructions to use.
+Guardian is purely API-driven. It is very easy to get started with Guardian. It provides CLI, HTTP and GRPC APIs for simpler developer experience.
+
+### CLI
+
+Guardian CLI is fully featured and simple to use, even for those who have very limited experience working from the command line. Run `guardian --help` to see list of all available commands and instructions to use.
 
 ```
+# List of commands
 $ guardian --help
-Universal access control to cloud apps and infrastructure.
-
-USAGE
-  guardian <command> <subcommand> [flags]
-
-CORE COMMANDS
-  appeal      Manage appeals
-  policy      Manage policies
-  provider    Manage providers
-  resource    Manage resources
-
-DEV COMMANDS
-  migrate     Run database migrations
-  serve       Run guardian server
-
-ADDITIONAL COMMANDS
-  completion  generate the autocompletion script for the specified shell
-  config      Manage client configuration settings
-  help        Help about any command
-  version     Print version information
-
-FLAGS
-  --help   Show help for command
-
-EXAMPLES
-  $ guardian appeal create
-  $ guardian policy list
-  $ guardian provider list
-  $ guardian resource list
-  $ guardian policy create --file policy.yaml
-
-ENVIRONMENT VARIABLES
-  See 'guardian help environment' for the list of supported environment variables.
-
-LEARN MORE
-  Use 'guardian <command> <subcommand> --help' for more information about a command.
-  Read the manual at https://odpf.github.io/guardian/
-
-FEEDBACK
-  Open an issue here https://github.com/odpf/guardian/issues
+
+# Print command reference
+$ guardian reference
 ```
 
+### API
+
+Guardian provides a fully-featured GRPC and HTTP API to interact with Guardian server. Both APIs adheres to a set of standards that are rigidly followed. Please refer to [proton](https://github.com/odpf/proton/tree/main/odpf/guardian/v1beta1) for GRPC API definitions.
+
 ## Running locally
 
 <details>
@@ -127,10 +99,10 @@ $ cp internal/server/config.yaml config.yaml
 $ ./guardian config init
 
 # Run database migrations
-$ ./guardian migrate
+$ ./guardian server migrate
 
 # Start guardian server
-$ ./guardian serve
+$ ./guardian server start
 ```
 
 ## Running tests

diff --git a/docs/blog/2021-08-20-guardian-launch.md b/docs/blog/2021-08-20-guardian-launch.md
diff --git a/docs/blog/authors.yml b/docs/blog/authors.yml
diff --git a/docs/docs/concepts/architecture.md → docs/docs/contribute/architecture.md b/docs/docs/concepts/architecture.md → docs/docs/contribute/architecture.md
diff --git a/docs/docs/getting_started/configuration.md b/docs/docs/getting_started/configuration.md
@@ -0,0 +1,104 @@
+# Configuration
+
+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/)
+
+Following is a sample server configuration yaml:
+
+```yaml
+PORT: 3000
+LOG:
+  LEVEL: info # debug|info|warning|error|fatal - default: info
+DB:
+  HOST: localhost      
+  USER: your_user
+  PASSWORD: your_password
+  NAME: guardian
+  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" 
+  EXPIRING_ACCESS_NOTIFICATION_INTERVAL: '0 9 * * *' # Default:"0 9 * * *" which means "At minute 0 past hour 9"
+```
+
+<!-- TODO: add documentation for notifier messsages -->
+
+#### Starting the server
+
+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
+```
+
+To run the Guardian server use command:
+
+```sh
+$ guardian server start
+```
+
+##### Using `--config` flag
+
+```sh
+$ guardian server migrate --config=<path-to-file>
+```
+
+```sh
+$ guardian server start --config=<path-to-file>
+```
+
+##### Using environment variables
+
+All the configs can be passed as environment variables using underscore `_` as the delimiter between nested keys. See the following examples
+
+```yaml
+PORT: 8080
+DB:
+  HOST: localhost
+  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              |
+
+Set the env variable using export
+```
+$ 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: 
+
+```yaml
+host: "localhost:8080"
+```
diff --git a/docs/docs/getting_started/installation.md b/docs/docs/getting_started/installation.md
@@ -0,0 +1,61 @@
+# Installation
+
+There are several approaches to install Guardian CLI
+
+1. [Using a pre-compiled binary](#binary-cross-platform)
+2. [Installing with package manager](#homebrew-installation)
+3. [Installing from source](#building-from-source)
+
+### Binary (Cross-platform)
+
+Guardian binaries are downloadable on the [Releases page](https://github.com/odpf/guardian/releases). Currently, the installer is not available. Once downloaded, the binary can be run from anywhere. You don’t need to install it in a global location. This works well for shared hosts and other systems where you don’t have a privileged account. Ideally, you should install it somewhere in your PATH for easy use. `/usr/local/bin` is the most probable location.
+
+### Homebrew Installation
+
+```sh
+# Install guardian (requires homebrew installed)
+$ brew install odpf/taps/guardian
+
+# Upgrade guardian (requires homebrew installed)
+$ brew upgrade guardian
+
+# Check for installed guardian version
+$ guardian version
+```
+
+### Building from source
+
+#### Prerequisites
+
+Guardian requires the following dependencies:
+
+- Golang (version 1.17 or above)
+- Git
+
+#### Build
+
+Run either of the following commands to clone and compile Guardian from source
+
+```sh
+$ git clone [email protected]:odpf/guardian.git  (Using SSH Protocol) Or
+$ git clone https://github.com/odpf/guardian.git (Using HTTPS Protocol)
+```
+
+```
+# Install all the golang dependencies
+$ make install
+
+# Check all build commands available
+$ make help
+
+# Build Guardian binary file
+$ make build
+```
+
+### Verifying the installation
+
+To verify if Guardian is properly installed, run `guardian --help` on your system. You should see help output. If you are executing it from the command line, make sure it is on your PATH or you may get an error about Guardian not being found.
+
+```
+$ guardian --help
+```
diff --git a/docs/docs/guides/approve-reject-appeal.md b/docs/docs/guides/approve-reject-appeal.md
@@ -0,0 +1,55 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Approve/Reject Appeal
+
+Note: Approve/reject still not supported from the CLI currently.
+
+#### Appeals can be approved/rejected in the following ways:
+
+1. Using `guardian appeal approve/reject` CLI command
+2. Calling to `POST /api/v1beta1/appeals/:id/approvals/:approval_step_name/` API
+
+<Tabs groupId="api">
+  <TabItem value="cli" label="CLI" default>
+
+#### Approve an Appeal
+
+```bash
+$ guardian appeal approve --id={{appeal_id}} --step={{approval_step_name}}
+```
+
+#### Reject an Appeal
+
+```bash
+$ guardian appeal reject --id={{appeal_id}} --step={{approval_step_name}} --reason={{rejection_message}}
+```
+
+  </TabItem>
+  <TabItem value="http" label="HTTP">
+
+#### Approve an Appeal
+
+```bash
+$ curl --request POST '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_step_name}}' \
+--header 'X-Auth-Email: [email protected]' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "action": "approve"
+}'
+```
+
+#### Reject an Appeal
+
+```bash
+$ curl --request POST '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_step_name}}' \
+--header 'X-Auth-Email: [email protected]' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "action": "reject",
+    "reason": "{{rejection_message}}"
+}'
+```
+
+  </TabItem>
+</Tabs>