From 62e2d6cce17ea8e509869126fcbdca574f2e682c Mon Sep 17 00:00:00 2001 From: Jeff Malnick Date: Mon, 27 Jul 2020 10:59:08 -0700 Subject: [PATCH] docs: add domain model docs (#218) --- website/data/docs-navigation.js | 20 ++++++++- .../pages/docs/configuration/auth-methods.mdx | 9 ---- website/pages/docs/configuration/grants.mdx | 9 ---- website/pages/docs/configuration/groups.mdx | 9 ---- website/pages/docs/configuration/projects.mdx | 9 ---- website/pages/docs/configuration/roles.mdx | 9 ---- website/pages/docs/configuration/users.mdx | 9 ---- website/pages/docs/domain-model/actions.mdx | 21 +++++++++ .../pages/docs/domain-model/auth-methods.mdx | 27 ++++++++++++ website/pages/docs/domain-model/grants.mdx | 36 ++++++++++++++++ website/pages/docs/domain-model/groups.mdx | 43 +++++++++++++++++++ .../pages/docs/domain-model/host-catalogs.mdx | 13 ++++++ website/pages/docs/domain-model/host-sets.mdx | 13 ++++++ website/pages/docs/domain-model/hosts.mdx | 13 ++++++ .../{configuration => domain-model}/index.mdx | 4 +- .../pages/docs/domain-model/organization.mdx | 19 ++++++++ .../pages/docs/domain-model/principals.mdx | 11 +++++ website/pages/docs/domain-model/projects.mdx | 39 +++++++++++++++++ website/pages/docs/domain-model/resources.mdx | 11 +++++ website/pages/docs/domain-model/roles.mdx | 39 +++++++++++++++++ website/pages/docs/domain-model/scopes.mdx | 11 +++++ website/pages/docs/domain-model/targets.mdx | 13 ++++++ website/pages/docs/domain-model/users.mdx | 41 ++++++++++++++++++ 23 files changed, 370 insertions(+), 58 deletions(-) delete mode 100644 website/pages/docs/configuration/auth-methods.mdx delete mode 100644 website/pages/docs/configuration/grants.mdx delete mode 100644 website/pages/docs/configuration/groups.mdx delete mode 100644 website/pages/docs/configuration/projects.mdx delete mode 100644 website/pages/docs/configuration/roles.mdx delete mode 100644 website/pages/docs/configuration/users.mdx create mode 100644 website/pages/docs/domain-model/actions.mdx create mode 100644 website/pages/docs/domain-model/auth-methods.mdx create mode 100644 website/pages/docs/domain-model/grants.mdx create mode 100644 website/pages/docs/domain-model/groups.mdx create mode 100644 website/pages/docs/domain-model/host-catalogs.mdx create mode 100644 website/pages/docs/domain-model/host-sets.mdx create mode 100644 website/pages/docs/domain-model/hosts.mdx rename website/pages/docs/{configuration => domain-model}/index.mdx (85%) create mode 100644 website/pages/docs/domain-model/organization.mdx create mode 100644 website/pages/docs/domain-model/principals.mdx create mode 100644 website/pages/docs/domain-model/projects.mdx create mode 100644 website/pages/docs/domain-model/resources.mdx create mode 100644 website/pages/docs/domain-model/roles.mdx create mode 100644 website/pages/docs/domain-model/scopes.mdx create mode 100644 website/pages/docs/domain-model/targets.mdx create mode 100644 website/pages/docs/domain-model/users.mdx diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index a6ce4ad075..28eaf47dc4 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -13,8 +13,24 @@ export default [ content: ['terminology', 'domain-model', 'reference-deployment'], }, { - category: 'configuration', - content: ['auth-methods', 'projects', 'users', 'groups', 'roles', 'grants'], + category: 'domain-model', + content: [ + 'actions', + 'auth-methods', + 'grants', + 'groups', + 'hosts', + 'host-catalogs', + 'host-sets', + 'organization', + 'principals', + 'projects', + 'resources', + 'scopes', + 'targets', + 'roles', + 'users', + ], }, { category: 'command-line', diff --git a/website/pages/docs/configuration/auth-methods.mdx b/website/pages/docs/configuration/auth-methods.mdx deleted file mode 100644 index 462d2e6958..0000000000 --- a/website/pages/docs/configuration/auth-methods.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: docs -page_title: Configuration -sidebar_title: Authentication Methods -description: |- - How to configure Watchtower authentication methods ---- - -# Authentication Methods diff --git a/website/pages/docs/configuration/grants.mdx b/website/pages/docs/configuration/grants.mdx deleted file mode 100644 index ffb49cc05f..0000000000 --- a/website/pages/docs/configuration/grants.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: docs -page_title: Configuration -sidebar_title: Grants -description: |- - How to configure Watchtower grants ---- - -# Grants diff --git a/website/pages/docs/configuration/groups.mdx b/website/pages/docs/configuration/groups.mdx deleted file mode 100644 index a551a130d9..0000000000 --- a/website/pages/docs/configuration/groups.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: docs -page_title: Configuration -sidebar_title: Groups -description: |- - How to configure Watchtower groups ---- - -# Groups diff --git a/website/pages/docs/configuration/projects.mdx b/website/pages/docs/configuration/projects.mdx deleted file mode 100644 index 5f4c635faa..0000000000 --- a/website/pages/docs/configuration/projects.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: docs -page_title: Configuration -sidebar_title: Projects -description: |- - How to configure Watchtower projects ---- - -# Projects diff --git a/website/pages/docs/configuration/roles.mdx b/website/pages/docs/configuration/roles.mdx deleted file mode 100644 index 933089f1e0..0000000000 --- a/website/pages/docs/configuration/roles.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: docs -page_title: Configuration -sidebar_title: Roles -description: |- - How to configure Watchtower roles ---- - -# Roles diff --git a/website/pages/docs/configuration/users.mdx b/website/pages/docs/configuration/users.mdx deleted file mode 100644 index a353b56425..0000000000 --- a/website/pages/docs/configuration/users.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: docs -page_title: Configuration -sidebar_title: Users -description: |- - How to configure Watchtower users ---- - -# Users diff --git a/website/pages/docs/domain-model/actions.mdx b/website/pages/docs/domain-model/actions.mdx new file mode 100644 index 0000000000..b79c767f13 --- /dev/null +++ b/website/pages/docs/domain-model/actions.mdx @@ -0,0 +1,21 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Action +description: |- + The annatomy of a Watchtower action +--- + +# Action + +An action is a defined capability within the Watchtower system. Each Resource Type defines its own set of Actions. Currently, the union of actions from all Resource Types is: create, read, update, delete, list, connect. This is not a fixed list and no design or implementation should assume it will ever be a fixed list. + +## Attributes + +For information on how actions are constructed into grant strings, see the [grants]() section. + +## Referenced By + +- [Grant]() +- [Resource]() +- [Role]() diff --git a/website/pages/docs/domain-model/auth-methods.mdx b/website/pages/docs/domain-model/auth-methods.mdx new file mode 100644 index 0000000000..5ee13707dc --- /dev/null +++ b/website/pages/docs/domain-model/auth-methods.mdx @@ -0,0 +1,27 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Authentication Methods +description: |- + How to configure Watchtower authentication methods +--- + +# Authentication Methods + +An authentication method is a method configured for an Organization to authenticate Users. The configuration of an Authentication Method may contain secrets. Zero or one Authentication Method can be configured to create Users. Creation of Groups may be added later. An Authentication Method is owned by one and only one Organization. An Authentication Method creates and references zero or more Users. An Authentication Method is deleted when the Organization it belongs to is deleted. The lifecycle of an Authentication Method is not tied to the lifecycle of any User. + +```shell-session ++---------------------------------------------+ +| Organization | ++---------------------------------------------+ +| Auth OIDC 1 | Auth OIDC 2 | Auth Userpass 1 | ++---------------------------------------------+ +``` + +# Attributes + +### ID + +An authentication method ID has a `am_` prefix followed by ten digits. + +Example: `am_0123456789` diff --git a/website/pages/docs/domain-model/grants.mdx b/website/pages/docs/domain-model/grants.mdx new file mode 100644 index 0000000000..e04ca7907e --- /dev/null +++ b/website/pages/docs/domain-model/grants.mdx @@ -0,0 +1,36 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Grants +description: |- + How to configure Watchtower grants +--- + +# Grants + +A grant represents a set of capabilities granted to a roley. It couples a set of Actions to either a set of Resource Types or an individual Resource. A Direct Grant belongs exclusively to one and only one Role. However, equivalent Direct Grants may exist across different Roles. A Direct Grant references one or more Actions and either one or more Resource types or one specific Resource. A Direct Grant is deleted when the Role it belongs to is deleted. A Direct Grant is also deleted if it is associated with a specific Resource and that Resource itself is deleted. The lifecycle of a Direct Grant is not tied to the lifecycle of any Action or Resource Type. + +```shell-session ++----------------------------------------+ +| Organization | ++--------------------+-------------------+ +| Role 1 | Role 2 | ++----------+-----------------------------+ +| Grant 1 | Grant 2 | Grant 1 | ++----------+---------+-------------------+ +``` + +## Attributes + +Direct grants are represented by strings of actions on resources. + +Example: `id=p_0123456789; action=read` + +The above example grants `read` action on the `p_0123456789` project resource. + +The glob `*` pattern can be used on IDs and actions as well: `id=*;action=*`, will allow all actions on all resources. + +## Referenced By + +- [Action]() +- [Role]() diff --git a/website/pages/docs/domain-model/groups.mdx b/website/pages/docs/domain-model/groups.mdx new file mode 100644 index 0000000000..ea263d3e45 --- /dev/null +++ b/website/pages/docs/domain-model/groups.mdx @@ -0,0 +1,43 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Group +description: |- + How to configure a Watchtower group +--- + +# Group + +Groups are collections of Users used only for access control purposes. A Group is owned by one and only one Scope. A Group can contain zero or more Users. A Group inherits from Principal ("is-a" Principal) allowing it to be associated with zero or more Roles. All Users in a Group are granted the capabilities of all Roles the Group is associated with. A Group is deleted when the Scope it belongs to is deleted. The lifecycle of a Group is not tied to the lifecycle of any User or Role. + +```shell-session ++-------------------------------------+ +| Organization | ++--------------------------+----------+ +| Group 1 | Group 2 | ++--------+--------+-------------------+ +| User 1 | User 2 | User 3 | User 4 | ++--------+--------+--------+----------+ +``` + +# Attributes + +### ID + +A group ID has a `g_` prefix followed by ten digits. + +Example: `g_0123456789` + +### Name + +A group name is the friendly name of a group resource. + +### Description + +A group description is the friendly description of the group resource. + +# Referenced By + +- [User]() +- [Role]() +- [Organization]() diff --git a/website/pages/docs/domain-model/host-catalogs.mdx b/website/pages/docs/domain-model/host-catalogs.mdx new file mode 100644 index 0000000000..40d8ab2289 --- /dev/null +++ b/website/pages/docs/domain-model/host-catalogs.mdx @@ -0,0 +1,13 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Host Catalog +description: |- + The annatomy of a Watchtower host catalog +--- + +# Host Catalog + +A host catalog is a permission boundary modeled as a container. A Host Catalog can contain Scopes forming a tree. A Scope can own zero to many Groups, Roles, Targets, and Host Catalogs. Scope is abstract. Organization and Project are concrete Scopes. All resources owned by a Scope are deleted when the Scope is deleted. + +## Attributes diff --git a/website/pages/docs/domain-model/host-sets.mdx b/website/pages/docs/domain-model/host-sets.mdx new file mode 100644 index 0000000000..4417960142 --- /dev/null +++ b/website/pages/docs/domain-model/host-sets.mdx @@ -0,0 +1,13 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Host Set +description: |- + The annatomy of a Watchtower host set +--- + +# Host Set + +A host set is a resource which provides a subset of Hosts from the set of Hosts of the Host Catalog it belongs to. A Host Set belongs to one and only one Host Catalog. A Host Set can contain zero or more Hosts. A Host Set can be contained by zero or more Targets. Host Set is abstract. A Host Set is deleted when the Host Catalog it belongs to is deleted. The lifecycle of a Host Set is not tied to the lifecycle of any Targets or Hosts. + +## Attributes diff --git a/website/pages/docs/domain-model/hosts.mdx b/website/pages/docs/domain-model/hosts.mdx new file mode 100644 index 0000000000..d0ff2aafdd --- /dev/null +++ b/website/pages/docs/domain-model/hosts.mdx @@ -0,0 +1,13 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Host +description: |- + The annatomy of a Watchtower host +--- + +# Host + +A host is a computing element with a network address reachable from Watchtower. A Host belongs to one and only one Host Catalog. A Host can be contained by zero or more Host Sets. Host is abstract. A Host is deleted when the Host Catalog it belongs to is deleted. The lifecycle of a Host is not tied to the lifecycle of any Host Sets. + +## Attributes diff --git a/website/pages/docs/configuration/index.mdx b/website/pages/docs/domain-model/index.mdx similarity index 85% rename from website/pages/docs/configuration/index.mdx rename to website/pages/docs/domain-model/index.mdx index 34c91b3356..f581dba5b2 100644 --- a/website/pages/docs/configuration/index.mdx +++ b/website/pages/docs/domain-model/index.mdx @@ -1,7 +1,7 @@ --- layout: docs -page_title: Configuration Index -sidebar_title: Configuration +page_title: Domain Model Index +sidebar_title: Domain Model description: |- Reference documentation for configuring Watchtower --- diff --git a/website/pages/docs/domain-model/organization.mdx b/website/pages/docs/domain-model/organization.mdx new file mode 100644 index 0000000000..bc3b3d7c68 --- /dev/null +++ b/website/pages/docs/domain-model/organization.mdx @@ -0,0 +1,19 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Organization +description: |- + The annatomy of a Watchtower organization +--- + +# Organization + +An Organization is a top-level container, and owns zero to many Projects and zero to many Authentication Methods. An Organization inherits from Scope ("is-a" Scope) allowing it to own zero to many Groups, Roles, Policies, Targets, Host Catalogs or Credential Stores. When an Organization is deleted, all resources owned by it are also deleted. The lifecycle of an Organization is not tied to anything else. A Role at the Organization level can grant permissions at the Project level. + +# Attributes + +### ID + +An organization ID is the character `o_` followed by ten digits. + +Example: `o_0123456789` diff --git a/website/pages/docs/domain-model/principals.mdx b/website/pages/docs/domain-model/principals.mdx new file mode 100644 index 0000000000..a187db397e --- /dev/null +++ b/website/pages/docs/domain-model/principals.mdx @@ -0,0 +1,11 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Principal +description: |- + The annatomy of a Watchtower principal +--- + +# Principal + +A principal is any entity which can be assigned capabilities. Principal is abstract. User, Group, and Project are concrete Principals. A Principal can be assigned to zero or more Roles. diff --git a/website/pages/docs/domain-model/projects.mdx b/website/pages/docs/domain-model/projects.mdx new file mode 100644 index 0000000000..dfbfa3456d --- /dev/null +++ b/website/pages/docs/domain-model/projects.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Project +description: |- + How to configure Watchtower projects +--- + +# Project + +A project is a child scope of an organization and is owned by an Organization. A Project inherits from Scope ("is-a" Scope) allowing it to own zero to many Groups, Roles, Policies, Targets, Host Catalogs or Credential Stores. A Project also inherits from Principal ("is-a" Principal) allowing it to be associated with zero or more Roles. A Project has no additional relationships beyond those defined in Scope and Principal. A Project is deleted when the Organization it belongs to is deleted. When a Project is deleted, all resources owned by it are also deleted. The lifecycle of a Project is not tied to any resource it contains. + +```shell-session ++-----------------------------------+ +| Organization | ++-----------------------------------+ +| Project 1 | Project 2 | Project 3 | ++-----------------------------------+ +``` + +# Attributes + +### ID + +A project ID is the character `p_` followed by ten digits. + +Example: `p_0123456789` + +### Name + +A project name is the friendly name set by the user of a project. + +### Description + +A project description is the friendly description set by the user. + +# Referenced By + +- [Organization]() diff --git a/website/pages/docs/domain-model/resources.mdx b/website/pages/docs/domain-model/resources.mdx new file mode 100644 index 0000000000..0fe494927b --- /dev/null +++ b/website/pages/docs/domain-model/resources.mdx @@ -0,0 +1,11 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Resource +description: |- + The annatomy of a Watchtower resource +--- + +# Resource + +A resource is an instance of one of the Resource Types. Resource is abstract. A Resource can be associated with zero or more Direct Grants. A resource can be any one of the following: organization, project, authentication-method, group, role, target, host-catalog, host-set, credential-catalog, credential-set. diff --git a/website/pages/docs/domain-model/roles.mdx b/website/pages/docs/domain-model/roles.mdx new file mode 100644 index 0000000000..c98bf6ded6 --- /dev/null +++ b/website/pages/docs/domain-model/roles.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Roles +description: |- + How to configure Watchtower roles +--- + +# Roles + +A role is a collection of capabilities granted to any Principal the Role is assigned to. A Role belongs to one and only one Scope. A Role owns zero or more Direct Grants. A Role can be assigned to zero or more Principals. A Principal assigned a Role receives all capabilities granted by any Direct Grant owned by the Role. A Role is deleted when the Scope it belongs to is deleted. All Direct Grants owned by a Role are deleted when the Role is deleted. The lifecycle of a Role is not tied to the lifecycle of any Principal. + +```shell-session ++---------------------------------+ +| Organization | ++----------------+----------------+ +| Role 1 | Role 2 | ++----------------+----------------+ +``` + +## Attributes + +### ID + +A role is prefixed with `r_` followed by ten digits. + +Example: `r_0123456789` + +### Users + +A role can have zero or more users associated with it. + +### Groups + +A role can have zero or more groups assocaited with it. + +### Grants + +A role can have zero or more grants associated with it. diff --git a/website/pages/docs/domain-model/scopes.mdx b/website/pages/docs/domain-model/scopes.mdx new file mode 100644 index 0000000000..7a84f1151a --- /dev/null +++ b/website/pages/docs/domain-model/scopes.mdx @@ -0,0 +1,11 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Scope +description: |- + The annatomy of a Watchtower scope +--- + +# Scope + +A scope is a permission boundary modeled as a container. A Scope can contain Scopes forming a tree. A Scope can own zero to many Groups, Roles, Policies, Targets, Host Catalogs and Credential Stores. Scope is abstract. Organization and Project are concrete Scopes. All resources owned by a Scope are deleted when the Scope is deleted. diff --git a/website/pages/docs/domain-model/targets.mdx b/website/pages/docs/domain-model/targets.mdx new file mode 100644 index 0000000000..4f986111e7 --- /dev/null +++ b/website/pages/docs/domain-model/targets.mdx @@ -0,0 +1,13 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: Target +description: |- + The annatomy of a Watchtower target +--- + +# Target + +A target is a networked service a User can connect to and interact with through Watchtower. A Target does not directly contain any secrets. A Target contains a collection of Hosts. A Target belongs to one and only one Scope. A Target can contain zero or more Host Sets. Target is abstract. A Target is deleted when the Scope it belongs to is deleted. The lifecycle of a Target is not tied to the lifecycle of any Host Set. + +## Attributes diff --git a/website/pages/docs/domain-model/users.mdx b/website/pages/docs/domain-model/users.mdx new file mode 100644 index 0000000000..ea173d0d92 --- /dev/null +++ b/website/pages/docs/domain-model/users.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: Configuration +sidebar_title: User +description: |- + How to configure a Watchtower user +--- + +# User + +A user is any entity authorized to access Watchtower using authentication credentials specific to one of the configured Authentication Methods. A User is owned by one and only one Organization. A User is associated with zero or one Authentication Methods. A User not associated with an Authentication Method can not log in to the system. A User can belong to zero or more Groups. A User inherits from Principal ("is-a" Principal) allowing it to be associated with zero or more Roles. A User is deleted when the Organization it belongs to is deleted. The lifecycle of a User is not tied to the lifecycle of any Authentication Method, Group or Role, but rather to its Organization only + +```shell-session ++-------------------------------------+ +| Organization | ++-------------------------------------+ +| User 1 | User 2 | User 3 | ++-------------------------------------+ +``` + +# Attributes + +### ID + +A user ID has a `u_` prefix followed by ten digits. + +Example: `u_0123456789` + +### Name + +A user name is the friendly name of a user resource. + +### Description + +A user description is the friendly description of the user resource. + +# Referenced By + +- [Groups]() +- [Roles]() +- [Organization]()