diff --git a/architecture/core_concepts/projects_and_users.adoc b/architecture/core_concepts/projects_and_users.adoc index 69fbce4ed819..a2f3290822f5 100644 --- a/architecture/core_concepts/projects_and_users.adoc +++ b/architecture/core_concepts/projects_and_users.adoc @@ -10,12 +10,80 @@ toc::[] +== Users + +Interaction with OpenShift is associated with a +user. An OpenShift user object represents an +actor which may be granted permissions in the system by +link:../../admin_guide/manage_authorization_policy.html#managing-role-bindings[adding +roles to them or to their groups]. + +Several types of users can exist: + +[cols="1,4"] +|=== + +|*Regular users* +|This is the way most interactive OpenShift users will be +represented. Regular users are created automatically in the system upon +first login, or can be created via the API. Regular users are represented +with the `*User*` object. Examples: `joe` `alice` + +|*System users* +|Many of these are created automatically when the infrastructure + is defined, mainly for the purpose of enabling the infrastructure to + interact with the API securely. They include a cluster administrator + (with access to everything), a per-node user, users for use by routers + and registries, and various others. Finally, there is an `*anonymous*` + system user that is used by default for unauthenticated requests. Examples: +`system:admin` `system:openshift-registry` `system:node:node1.example.com` + +|*Service accounts* +|These are special system users associated with projects; some are created automatically when +the project is first created, while project administrators can create more +for the purpose of defining access to the contents of each link:#projects[project]. +Service accounts are represented with the `*ServiceAccount*` object. Examples: +`system:serviceaccount:default:deployer` `system:serviceaccount:foo:builder` + +|=== + +Every user must link:../additional_concepts/authentication.html[authenticate] in some way in order to access OpenShift. +API requests with no authentication or invalid authentication are authenticated as requests by the `*anonymous*` system user. +Once authenticated, policy determines what the user is link:../additional_concepts/authorization.html[authorized] to do. + +== Namespaces + +A Kubernetes namespace provides a mechanism to scope resources in a cluster. +In OpenShift, a link:#projects[project] is a Kubernetes namespace with +additional annotations. + +Namespaces provide a unique scope for: + +- Named resources to avoid basic naming collisions. +- Delegated management authority to trusted users. +- The ability to limit community resource consumption. + +Most objects in the system are scoped by namespace, but some are +excepted and have no namespace, including nodes and users. + +See the +https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/namespaces.md[Kubernetes +documentation] for more information on namespaces. + == Projects +A project is a Kubernetes namespace with additional annotations, and is the central vehicle +by which access to resources for regular users is managed. A project allows a community of users to organize and manage their content in -isolation from other communities. A project is a Kubernetes namespace with -additional annotations. +isolation from other communities. Users must be given access to projects by administrators, +or if allowed to create projects, automatically have access to their own projects. + +Projects can have a separate `*name*`, `*displayName*`, and `*description*`. + +- The mandatory `*name*` is a unique identifier for the project and is most visible when using the CLI tools or API. +- The optional `*displayName*` is how the project is displayed in the web console (defaults to `*name*`). +- The optional `*description*` can be a more detailed description of the project and is also visible in the web console. -Each project has its own set of: +Each project scopes its own set of: [cols="1,4"] |=== @@ -24,10 +92,13 @@ Each project has its own set of: |Pods, services, replication controllers, etc. |*Policies* -|Who can or cannot perform actions. +|Rules for which users can or cannot perform actions on objects. |*Constraints* -|Project quotas. +|Quotas for each kind of object that can be limited. + +|*Service accounts* +|Service accounts act automatically with designated access to objects in the project. |=== @@ -41,49 +112,3 @@ link:../../admin_guide/selfprovisioned_projects.html[their own projects]. Developers and administrators can link:../../dev_guide/projects.html[interact with projects] using link:../../cli_reference/overview.html[the CLI] or the link:../infrastructure_components/web_console.html[web console]. - -.Project Object Definition -==== - -[source,json] ----- -{ - "kind": "Project", - "apiVersion": "v1", - "metadata": { - "name": "hello-openshift", - "selfLink": "/osapi/v1/projects/hello-openshift", - "uid": "72565b98-de1d-11e4-bab4-28d2444e470d", - "resourceVersion": "681", - "creationTimestamp": "2015-04-08T18:31:18Z", - "annotations": { - "description": "This is an example project to demonstrate OpenShift v3", - "displayName": "Hello OpenShift", - "displayname": "Hello OpenShift" - } - }, - "spec": { - "finalizers": [ - "openshift.com/project", - "kubernetes" - ] - } -} ----- -==== - -== Namespaces - -A namespace provides a mechanism to subdivide resources in a Kubernetes cluster. -In OpenShift, a link:#projects[project] is a Kubernetes namespace with -additional annotations. - -Namespaces provides a unique scope for: - -- Named resources to avoid basic naming collisions. -- Delegated management authority to trusted users. -- The ability to limit community resource consumption. - -See the -https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/namespaces.md[Kubernetes -documentation] for more information on namespaces.