Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation
Guide That Contains This Content
[+] Expand All
[-] Collapse All

    Configuring Multitenancy Support

    The following sections describe enabling and viewing multitenancy support.

    Multitenancy Permissions

    The multi tenancy feature of the API server enables multiple tenants to coexist on the system without interfering with each other. This is achieved by encoding ownership information and permissions with each resource, allowing fine-grained control over create, read, update, and delete (CRUD) operations on those resources.

    The Contrail api-server enforces resources permissions in a manner similar to Unix files. Each resource has an owner and group. Permissions associated with owner, group, and "others" are:

    • R - reading resource
    • W - create/update resource
    • X - link (refer to) object

    CRUD permission requirements for resources managed by api-server are as follows:

    • C - write on parent object

      For example, to create a virtual network requires write permission on the project.

    • R - read on object (parent if a collection)
    • U - write on object
    • D - write on parent
    • ref(link) - execute on object

      For example, on a virtual network using network-ipam, network-ipam should have X permissions for owner, group, or "others".

    API Server

    If multitenancy is enabled, api-server deploys keystone middleware in its pipeline. The keystone middleware architecture supports a common authentication protocol in use between OpenStack projects.

    The keystone middleware works in conjunction with api-server to derive the user name and role for each incoming request. Once obtained, the user name and role are matched against resource ownership and permissions. If the ownership matches or the permissions allow access, access is granted.

    For example, assume Tenant A has the following attributes:

    • owner = Bob
    • group = Staff
    • permisssions = 750

    In this example, only Bob can create a virtual network in Tenant A. Other staff members can view the virtual networks in Tenant A. No others can create or view any virtual networks in Tenant A.

    Clients can obtain an auth_token by posting credentials to the keystone admin API (/v2.0/tokens). The VncApi client library does this automatically. If an auth_token is present in an incoming request, api-server validates credentials derived from the token against object permissions. If an incoming request has an invalid or missing auth_token, a 401 error is returned.

    Notes:

    • Multitenancy is enabled by the flag multi_tenancy in /etc/contrail/api-server.conf
    • If multitenancy is enabled, memcaching is automatically enabled, to improve token validation response time.

    API Library Keystone Integration

    VncApi has been updated to check for any 401 error that api-server returns as a result of a missing or invalid token. This forces VncApi to connect with the keystone middleware and fetch an auth_token. All subsequent requests to api-server include the auth_token.

    Supporting Utilities

    • /opt/contrail/utils/chmod.py—- To change permissions and ownership (user or group membership) of a resource. Requires the resource type (for example, virtual-network) and the resource FQN (for example, default-domain:default-project:default-virtual-network).

      Invoke python /opt/contrail/utils/chmod.py -h to see usage information

      Example 1 - See current permissions:

      [root@host]# python /opt/contrail/utils/chmod.py <ip address>:8082 project default-domain:default-project 
      Type =  project   
      Name =  default-domain:default-project   
      API Server =  <ip address>:8082   
      Keystone credentials admin/<password>/admin   
      Obj uuid =  $ABC123   
      Obj perms = cloud-admin/cloud-admin-group 777    
      
      [root@host]# python /opt/contrail/utils/chmod.py <ip address>:8082 --owner foo --group bar --perms 555 project default-domain:default-project   
      Type =  project   Name =  default-domain:default-project   
      API Server =  <ip address>   
      Owner =  foo   
      Group =  bar   
      Perms =  555   
      Keystone credentials admin/<password>/admin   
      Obj uuid =  $ABC123   
      Obj perms = cloud-admin/cloud-admin-group 777  
       New perms = foo/bar 555
    • /opt/contrail/utils/multi_tenancy.py —- Show if multitenancy is enabled or disabled. Also used to turn multitenancy on or off. Requires admin credentials.

      Invoke python /opt/contrail/utils/multi_tenancy.py -h to see usage information

      Example 1: View multitenancy status

      [root@host]# python /opt/contrail/utils/multi_tenancy.py <ip address>:8082
      API Server =  <ip address>:8082   
      Keystone credentials admin/<password>/admin   
      
      Multi Tenancy is enabled
      

      Example 2: Turn multitenancy off

      [root@host]# python /opt/contrail/utils/multi_tenancy.py 10.84.13.34:8082 --off
      API Server =  <ip address>:8082
      Keystone credentials admin/<password>/admin
      
      Multi Tenancy is disabled
      
      

    Modified: 2016-06-13