Add Namespace Documentation

Explain the namespaces that are created and how they are used by other
services.

README.md

@@ -72,7 +72,9 @@ Other users are included in a project by associating it with a group, therefore
 
 Like most other components, flexibility is built in by design, so a project can be shared with multiple groups.
 
-## RBAC
+## Security
+
+### RBAC
 
 The identity service provides centralized role based access control to the unikorn suite of services.
 As described previously, roles can be arbitrary and apply to services outside of the identity service.
@@ -90,7 +92,7 @@ The ACL can be used to:
 
 There is a special shortcut for a "super admin" user, who as a platform administrator can see and do anything.
 
-## Scoping
+### Scoping
 
 Further to basic RBAC and ACLs, a second API details what the user can see.
 
@@ -100,3 +102,19 @@ You need to only be returned resources that belong to projects you have read acc
 Typically this information is used to construct label selectors for Unikorn services.
 
 This functionality piggy-backs on the `userinfo` OIDC API, but don't rely on that, instead a shared library provided by Unikorn Core should be used to provide this functionality in your services.
+
+## Integration with Other Services
+
+By itself, the identity service doesn't offer much functionality beyond simple OIDC authentication flows.
+Other services are responsibe for provisioning and managing actual resources.
+
+Because this is a multi-tenant system, we need a top level organization to be unique, this is acheived by having these all provisioned in the identity service's namepspace.
+We do anticipate most users to expect they can provision any cluster name they wish, so these must be provisioned in an organization specific namespace.
+Likewise, multiple projects within the same organization may want resources that are named the same in different projects, for example to facilitate different environments, so these need a project specific namespace too.
+
+![Resource](./docs/images/namespaces.png)
+
+The identity service manages all this for you automatically.
+Unique namespace names are automatically generated by the platform, and organization and project resources record this in their status for easy navigation.
+
+Other services, e.g. the core Kubernetes service can then consume the project namespace by heving their custom resources residing in there, separating them from other projects and other organizations.