Warning

NOTICE: THIS DOCUMENTATION SITE HAS BEEN SUPERSEDED.

For the current documentation site goto: http://docs.cloudstack.apache.org

Using Projects to Organize Users and Resources

Overview of Projects

Projects are used to organize people and resources. CloudStack users within a single domain can group themselves into project teams so they can collaborate and share virtual resources such as VMs, snapshots, templates, data disks, and IP addresses. CloudStack tracks resource usage per project as well as per user, so the usage can be billed to either a user account or a project. For example, a private cloud within a software company might have all members of the QA department assigned to one project, so the company can track the resources used in testing while the project members can more easily isolate their efforts from other users of the same cloud

You can configure CloudStack to allow any user to create a new project, or you can restrict that ability to just CloudStack administrators. Once you have created a project, you become that project’s administrator, and you can add others within your domain to the project. CloudStack can be set up either so that you can add people directly to a project, or so that you have to send an invitation which the recipient must accept. Project members can view and manage all virtual resources created by anyone in the project (for example, share VMs). A user can be a member of any number of projects and can switch views in the CloudStack UI to show only project-related information, such as project VMs, fellow project members, project-related alerts, and so on.

The project administrator can pass on the role to another project member. The project administrator can also add more members, remove members from the project, set new resource limits (as long as they are below the global defaults set by the CloudStack administrator), and delete the project. When the administrator removes a member from the project, resources created by that user, such as VM instances, remain with the project. This brings us to the subject of resource ownership and which resources can be used by a project.

Resources created within a project are owned by the project, not by any particular CloudStack account, and they can be used only within the project. A user who belongs to one or more projects can still create resources outside of those projects, and those resources belong to the user’s account; they will not be counted against the project’s usage or resource limits. You can create project-level networks to isolate traffic within the project and provide network services such as port forwarding, load balancing, VPN, and static NAT. A project can also make use of certain types of resources from outside the project, if those resources are shared. For example, a shared network or public template is available to any project in the domain. A project can get access to a private template if the template’s owner will grant permission. A project can use any service offering or disk offering available in its domain; however, you can not create private service and disk offerings at the project level..

Configuring Projects

Before CloudStack users start using projects, the CloudStack administrator must set up various systems to support them, including membership invitations, limits on project resources, and controls on who can create projects.

Setting Up Invitations

CloudStack can be set up either so that project administrators can add people directly to a project, or so that it is necessary to send an invitation which the recipient must accept. The invitation can be sent by email or through the user’s CloudStack account. If you want administrators to use invitations to add members to projects, turn on and set up the invitations feature in CloudStack.

  1. Log in as administrator to the CloudStack UI.

  2. In the left navigation, click Global Settings.

  3. In the search box, type project and click the search button. Searches projects

  4. In the search results, you can see a few other parameters you need to set to control how invitations behave. The table below shows global configuration parameters related to project invitations. Click the edit button to set each parameter.

    Configuration Parameters Description
    project.invite.required Set to true to turn on the invitations feature.
    project.email.sender The email address to show in the From field of invitation emails.
    project.invite.timeout Amount of time to allow for a new member to respond to the invitation.
    project.smtp.host Name of the host that acts as an email server to handle invitations.
    project.smtp.password (Optional) Password required by the SMTP server. You must also set project.smtp.username and set project.smtp.useAuth to true.
    project.smtp.port SMTP server’s listening port.
    project.smtp.useAuth Set to true if the SMTP server requires a username and password.
    project.smtp.username (Optional) User name required by the SMTP server for authentication. You must also set project.smtp.password and set project.smtp.useAuth to true..

  5. Restart the Management Server:

    service cloudstack-management restart

Setting Resource Limits for Projects

The CloudStack administrator can set global default limits to control the amount of resources that can be owned by each project in the cloud. This serves to prevent uncontrolled usage of resources such as snapshots, IP addresses, and virtual machine instances. Domain administrators can override these resource limits for individual projects with their domains, as long as the new limits are below the global defaults set by the CloudStack root administrator. The root administrator can also set lower resource limits for any project in the cloud

Setting Per-Project Resource Limits

The CloudStack root administrator or the domain administrator of the domain where the project resides can set new resource limits for an individual project. The project owner can set resource limits only if the owner is also a domain or root administrator.

The new limits must be below the global default limits set by the CloudStack administrator (as described in “Setting Resource Limits for Projects”). If the project already owns more of a given type of resource than the new maximum, the resources are not affected; however, the project can not add any new resources of that type until the total drops below the new limit.

  1. Log in as administrator to the CloudStack UI.
  2. In the left navigation, click Projects.
  3. In Select View, choose Projects.
  4. Click the name of the project you want to work with.
  5. Click the Resources tab. This tab lists the current maximum amount that the project is allowed to own for each type of resource.
  6. Type new values for one or more resources.
  7. Click Apply.

Setting the Global Project Resource Limits

  1. Log in as administrator to the CloudStack UI.

  2. In the left navigation, click Global Settings.

  3. In the search box, type max.projects and click the search button.

  4. In the search results, you will see the parameters you can use to set per-project maximum resource amounts that apply to all projects in the cloud. No project can have more resources, but an individual project can have lower limits. Click the edit button to set each parameter. Edits Parameters

    max.project.public.ips Maximum number of public IP addresses that can be owned by any project in the cloud. See About Public IP Addresses.
    max.project.snapshots Maximum number of snapshots that can be owned by any project in the cloud. See Working with Snapshots.
    max.project.templates Maximum number of templates that can be owned by any project in the cloud. See Working with Templates.
    max.project.uservms Maximum number of guest virtual machines that can be owned by any project in the cloud. See Working With Virtual Machines.
    max.project.volumes Maximum number of data volumes that can be owned by any project in the cloud. See Working with Volumes.

  5. Restart the Management Server.

    # service cloudstack-management restart

Setting Project Creator Permissions

You can configure CloudStack to allow any user to create a new project, or you can restrict that ability to just CloudStack administrators.

  1. Log in as administrator to the CloudStack UI.

  2. In the left navigation, click Global Settings.

  3. In the search box, type allow.user.create.projects.

  4. Click the edit button to set the parameter. Edits Parameters

    allow.user.create.projects

    Set to true to allow end users to create projects. Set to false if you want only the CloudStack root administrator and domain administrators to create projects.

  5. Restart the Management Server.

    # service cloudstack-management restart

Creating a New Project

CloudStack administrators and domain administrators can create projects. If the global configuration parameter allow.user.create.projects is set to true, end users can also create projects.

  1. Log in as administrator to the CloudStack UI.
  2. In the left navigation, click Projects.
  3. In Select view, click Projects.
  4. Click New Project.
  5. Give the project a name and description for display to users, then click Create Project.
  6. A screen appears where you can immediately add more members to the project. This is optional. Click Next when you are ready to move on.
  7. Click Save.

Adding Members to a Project

New members can be added to a project by the project’s administrator, the domain administrator of the domain where the project resides or any parent domain, or the CloudStack root administrator. There are two ways to add members in CloudStack, but only one way is enabled at a time:

  • If invitations have been enabled, you can send invitations to new members.
  • If invitations are not enabled, you can add members directly through the UI.

Sending Project Membership Invitations

Use these steps to add a new member to a project if the invitations feature is enabled in the cloud as described in “Setting Up Invitations”. If the invitations feature is not turned on, use the procedure in Adding Project Members From the UI.

  1. Log in to the CloudStack UI.
  2. In the left navigation, click Projects.
  3. In Select View, choose Projects.
  4. Click the name of the project you want to work with.
  5. Click the Invitations tab.
  6. In Add by, select one of the following:
    1. Account – The invitation will appear in the user’s Invitations tab in the Project View. See Using the Project View.
    2. Email – The invitation will be sent to the user’s email address. Each emailed invitation includes a unique code called a token which the recipient will provide back to CloudStack when accepting the invitation. Email invitations will work only if the global parameters related to the SMTP server have been set. See “Setting Up Invitations”.
  7. Type the user name or email address of the new member you want to add, and click Invite. Type the CloudStack user name if you chose Account in the previous step. If you chose Email, type the email address. You can invite only people who have an account in this cloud within the same domain as the project. However, you can send the invitation to any email address.
  8. To view and manage the invitations you have sent, return to this tab. When an invitation is accepted, the new member will appear in the project’s Accounts tab.

Adding Project Members From the UI

The steps below tell how to add a new member to a project if the invitations feature is not enabled in the cloud. If the invitations feature is enabled cloud,as described in “Setting Up Invitations”, use the procedure in “Sending Project Membership Invitations”.

  1. Log in to the CloudStack UI.
  2. In the left navigation, click Projects.
  3. In Select View, choose Projects.
  4. Click the name of the project you want to work with.
  5. Click the Accounts tab. The current members of the project are listed.
  6. Type the account name of the new member you want to add, and click Add Account. You can add only people who have an account in this cloud and within the same domain as the project.

Accepting a Membership Invitation

If you have received an invitation to join a CloudStack project, and you want to accept the invitation, follow these steps:

  1. Log in to the CloudStack UI.

  2. In the left navigation, click Projects.

  3. In Select View, choose Invitations.

  4. If you see the invitation listed onscreen, click the Accept button.

    Invitations listed on screen were sent to you using your CloudStack account name.

  5. If you received an email invitation, click the Enter Token button, and provide the project ID and unique ID code (token) from the email.

Suspending or Deleting a Project

When a project is suspended, it retains the resources it owns, but they can no longer be used. No new resources or members can be added to a suspended project.

When a project is deleted, its resources are destroyed, and member accounts are removed from the project. The project’s status is shown as Disabled pending final deletion.

A project can be suspended or deleted by the project administrator, the domain administrator of the domain the project belongs to or of its parent domain, or the CloudStack root administrator.

  1. Log in to the CloudStack UI.

  2. In the left navigation, click Projects.

  3. In Select View, choose Projects.

  4. Click the name of the project.

  5. Click one of the buttons:

    To delete, use Removes a project

    To suspend, use Suspends a project

Using the Project View

If you are a member of a project, you can use CloudStack’s project view to see project members, resources consumed, and more. The project view shows only information related to one project. It is a useful way to filter out other information so you can concentrate on a project status and resources.

  1. Log in to the CloudStack UI.
  2. Click Project View.
  3. The project dashboard appears, showing the project’s VMs, volumes, users, events, network settings, and more. From the dashboard, you can:
    • Click the Accounts tab to view and manage project members. If you are the project administrator, you can add new members, remove members, or change the role of a member from user to admin. Only one member at a time can have the admin role, so if you set another user’s role to admin, your role will change to regular user.
    • (If invitations are enabled) Click the Invitations tab to view and manage invitations that have been sent to new project members but not yet accepted. Pending invitations will remain in this list until the new member accepts, the invitation timeout is reached, or you cancel the invitation.