From 042986c290e6541230ccc0a8ee9ea96c21c2bd1f Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Wed, 6 Jul 2022 10:10:23 -0500 Subject: [PATCH] docs: update sidebar structure (#203) --- docs/docs/{guides => concepts}/overview.md | 0 docs/docs/guides/approve-reject-appeal.md | 2 +- docs/docs/guides/complex-use-case.md | 27 ++-- .../configuration.md | 30 +++-- docs/docs/guides/create-appeal.md | 116 +++++++++--------- docs/docs/guides/create-policy.md | 36 +++--- docs/docs/guides/create-provider.md | 2 +- docs/docs/guides/introduction.md | 2 +- docs/docs/guides/update-resource.md | 6 +- .../{getting_started => }/installation.md | 0 docs/docs/{overview => }/introduction.md | 2 +- docs/docs/providers/gcloud_iam.md | 8 +- docs/docs/reference/cli.md | 5 +- docs/docs/{overview => }/roadmap.md | 0 docs/docusaurus.config.js | 6 +- docs/sidebars.js | 26 ++-- docs/src/css/theme.css | 47 +++---- 17 files changed, 161 insertions(+), 154 deletions(-) rename docs/docs/{guides => concepts}/overview.md (100%) rename docs/docs/{getting_started => guides}/configuration.md (89%) rename docs/docs/{getting_started => }/installation.md (100%) rename docs/docs/{overview => }/introduction.md (94%) rename docs/docs/{overview => }/roadmap.md (100%) diff --git a/docs/docs/guides/overview.md b/docs/docs/concepts/overview.md similarity index 100% rename from docs/docs/guides/overview.md rename to docs/docs/concepts/overview.md diff --git a/docs/docs/guides/approve-reject-appeal.md b/docs/docs/guides/approve-reject-appeal.md index 5a88848ab..06d3ec843 100644 --- 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 index 74928dc35..bb594fc11 100644 --- 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 b/docs/docs/guides/configuration.md similarity index 89% rename from docs/docs/getting_started/configuration.md rename to docs/docs/guides/configuration.md index 3b568c11f..8e01ad364 100644 --- a/docs/docs/getting_started/configuration.md +++ b/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,11 +22,11 @@ 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: @@ -32,7 +34,7 @@ NOTIFIER: 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 index 65d626105..fadbda8dd 100644 --- 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": "user@company.com", + "role": "viewer", + "resource": { + "id": "<< playground resource id >>", + "provider_type": "bigquery", + "provider_urn": "my-first-bigquery-provider", + "type": "dataset", + "urn": "<>:playground", + "name": "playground", + "details": { + "owner": "owner.guy@company.com" + }, + "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": ["owner.guy@company.com"], + "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": "user@company.com", - "role": "viewer", - "resource": { - "id": "<< playground resource id >>", - "provider_type": "bigquery", - "provider_urn": "my-first-bigquery-provider", - "type": "dataset", - "urn": "<>:playground", - "name": "playground", - "details": { - "owner": "owner.guy@company.com" - }, - "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": [ - "owner.guy@company.com" - ], - "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": [ - "john.doe@company.com" - ], - "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": "user@company.com", - "creator": null + "id": "<< approval id 2 >>", + "name": "admin_approval", + "appeal_id": "<< appeal id >>", + "status": "blocked", + "policy_id": "my-first-policy", + "policy_version": 1, + "approvers": ["john.doe@company.com"], + "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": "user@company.com", + "creator": null + } + ] } -``` \ No newline at end of file +``` diff --git a/docs/docs/guides/create-policy.md b/docs/docs/guides/create-policy.md index a3038a43e..c2f0ab245 100644 --- 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: - - john.doe@company.com + - 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: + - john.doe@company.com ``` + Check [policy reference](../reference/policy.md) for more details on the policy configuration.
**Explanation of this Policy example**
-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:
+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:
+ 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 @@ -75,4 +77,4 @@ $ curl --request POST '{{HOST}}/api/v1beta1/policies' \ -**Note** : For using the CLI tool, create a Policy.yaml file using the example configurations shown above and provide the path to it here. \ No newline at end of file +**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 index 664f10d3f..603b6b5ca 100644 --- 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 index 7f17e2deb..431ed3a8e 100644 --- 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 index 500d92a21..b570aa259 100644 --- 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}}' ``` + To update the resource metadata with this information add this to the resource file or request body + ```yaml details: owner: owner.guy@company.com @@ -84,4 +86,4 @@ $ curl --request PUT '{{HOST}}/api/v1beta1/resources/{{resource_id}}' \ ``` - \ No newline at end of file + diff --git a/docs/docs/getting_started/installation.md b/docs/docs/installation.md similarity index 100% rename from docs/docs/getting_started/installation.md rename to docs/docs/installation.md diff --git a/docs/docs/overview/introduction.md b/docs/docs/introduction.md similarity index 94% rename from docs/docs/overview/introduction.md rename to docs/docs/introduction.md index 3aea0839e..f4df4fcd2 100644 --- a/docs/docs/overview/introduction.md +++ b/docs/docs/introduction.md @@ -30,7 +30,7 @@ Users are required to raise an appeal to gain access to a particular resource. T ## Where to go from here -See the [installation](../getting_started/installation) page to install the Guardian CLI. Next, we recommend completing the guides. The tour provides an overview of most of the existing functionality of Guardian and takes approximately 30 minutes to complete. +See the [installation](./installation) page to install the Guardian CLI. Next, we recommend completing the guides. The tour provides an overview of most of the existing functionality of Guardian and takes approximately 30 minutes to complete. After completing the tour, check out the remainder of the documentation in the reference and concepts sections for your specific areas of interest. We've aimed to provide as much documentation as we can for the various components of Guardian to give you a full understanding of Guardian's surface area. diff --git a/docs/docs/providers/gcloud_iam.md b/docs/docs/providers/gcloud_iam.md index 342ac06b7..4fe5e6f1c 100644 --- a/docs/docs/providers/gcloud_iam.md +++ b/docs/docs/providers/gcloud_iam.md @@ -1,4 +1,4 @@ -# Google Cloud IAM +# GCP ## Prerequisites @@ -57,9 +57,9 @@ resources: ### `GCloudIAMCredentials` -| Fields | | -| :--- | :--- | -| `resource_name` | `string` GCP Project ID in resource name format. Example: `projects/my-project-id`, `organizations/my-org-id`| +| Fields | | +| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `resource_name` | `string` GCP Project ID in resource name format. Example: `projects/my-project-id`, `organizations/my-org-id` | | `service_account_key` | `string` Service account key JSON that has [prerequisites permissions](#prerequisites). On provider creation, the value should be an base64 encoded JSON key. | ### `GCloudIAMResourceType` diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 9486824b8..509351e2a 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -1,6 +1,6 @@ # CLI -`Guardian` is a command line tool used to interact with the main guardian service. Follow the [installation](../getting_started/installation) and [configuration](../getting_started/configuration) guides to set up the CLI tool for Guardian. +`Guardian` is a command line tool used to interact with the main guardian service. Follow the [installation](../installation) and [configuration](../guides/configuration) guides to set up the CLI tool for Guardian. ## List of Commands @@ -482,10 +482,13 @@ This command supports the following flags: ``` -f, --file string updated resource file path ``` + ** Here is an example below:** + ```bash $ guardian resource set --id={{resource_id}} --values== --values== ``` + ### View Resource View a resource details diff --git a/docs/docs/overview/roadmap.md b/docs/docs/roadmap.md similarity index 100% rename from docs/docs/overview/roadmap.md rename to docs/docs/roadmap.md diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index a719512c5..774d22606 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -21,7 +21,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); docs: { sidebarPath: require.resolve('./sidebars.js'), editUrl: 'https://github.com/odpf/guardian/edit/master/docs/', - sidebarCollapsed: false, + sidebarCollapsed: true, breadcrumbs: false, }, blog: false, @@ -52,9 +52,9 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); items: [ { type: 'doc', - docId: 'overview/introduction', + docId: 'introduction', position: 'right', - label: 'Documentation', + label: 'Docs', }, { to: 'docs/support', label: 'Support', position: 'right' }, { diff --git a/docs/sidebars.js b/docs/sidebars.js index 0b89ce1c3..ebadccc25 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,19 +1,13 @@ module.exports = { docsSidebar: [ + 'introduction', + 'installation', + 'roadmap', { type: "category", - label: "Overview", + label: "Concepts", items: [ - "overview/introduction", - "overview/roadmap", - ], - }, - { - type: "category", - label: "Getting Started", - items: [ - "getting_started/installation", - "getting_started/configuration", + "concepts/overview", ], }, { @@ -21,7 +15,7 @@ module.exports = { label: "Guides", items: [ "guides/introduction", - "guides/overview", + "guides/configuration", "guides/create-policy", "guides/create-provider", "guides/update-resource", @@ -34,19 +28,13 @@ module.exports = { type: "category", label: "Providers", items: [ - "providers/bigquery", "providers/gcloud_iam", + "providers/bigquery", "providers/tableau", "providers/metabase", "providers/grafana", ], }, - // { - // type: "category", - // label: "Concepts", - // items: [ - // ], - // }, { type: "category", label: "Reference", diff --git a/docs/src/css/theme.css b/docs/src/css/theme.css index fd1c19c77..4d6796398 100644 --- a/docs/src/css/theme.css +++ b/docs/src/css/theme.css @@ -53,6 +53,10 @@ html[data-theme="dark"] { --dark-bg-color: #131313; } +.navbar{ + box-shadow:0 1px 1px 0 rgba(0, 0, 0, 0.08); +} + .container{ margin-top: 1rem; } @@ -74,15 +78,17 @@ html[data-theme="dark"] { padding-left: 0; } + .menu__link--sublist-caret{ - font-weight: 600; + font-weight: 500; color: var(--ifm-color-grey-darkest) !important; } .theme-doc-sidebar-item-category{ - padding-top: .3rem; + padding-top: .2rem; } +/* Content */ .markdown h1 { font-size: 2.5rem; } @@ -98,19 +104,13 @@ html[data-theme="dark"] { box-shadow: none !important; } -.pagination-nav__link{ - border: 1px solid var(--ifm-color-emphasis-200) -} - -.pagination-nav__sublabel{ - font-size: 60%; -} - -.pagination-nav__label{ +.tabs__item { + border-bottom-width: 1px; + padding:0.7rem 1rem; font-size: 80%; - font-weight: normal; } +/* Table design */ table{ font-size: 85%; width: 100%; @@ -156,21 +156,26 @@ code { padding: 0 3em } -.table-of-contents__left-border { - border-left: 0; +.tabs{ + border-bottom: 1px solid var(--ifm-color-emphasis-100); } -.navbar{ - box-shadow:0 1px 1px 0 rgba(0, 0, 0, 0.08); + +.pagination-nav__link{ + border: 1px solid var(--ifm-color-emphasis-200) } -.tabs{ - border-bottom: 1px solid var(--ifm-color-emphasis-100); +.pagination-nav__sublabel{ + font-size: 60%; } -.tabs__item { - border-bottom-width: 1px; - padding:0.7rem 1rem; +.pagination-nav__label{ font-size: 80%; + font-weight: normal; +} + +/* TOC */ +.table-of-contents__left-border { + border-left: 0; } .theme-doc-footer .col {