Merge pull request openshift#2 from sosiouxme/core_concepts_reorg-users

arch core: projects and users revamped

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.