Managing Projects

Page last updated:

The following procedures describe how to manage projects and project members with build service.

A project is a Build Service resource that simplifies kubernetes namespaces and RBAC to provide multi-tenancy for images, secrets, and builders.

Projects are optional, Build Service can be utilized without using projects.

Creating a Project

To create a new project:

pb project create PROJECT-NAME

Where PROJECT-NAME is a unique name for the project.

Listing Projects

To view projects of which the user is a member:

pb project list

Targeting a Project

Projects map to Kubernetes namespaces. Because of this, you should not create projects with the same name as pre-existing Kubernetes namespaces.

The user who creates the project is added to the project as its first member. Because of this, you cannot access resources produced by Build Service globally across all the namespaces in the cluster.

To target a project:

pb project target PROJECT-NAME

Where PROJECT-NAME is the name of your project.

After you have targeted a project, Build Service assumes that the commands you run are for that project.

In order to target a different project, run the command again and specify a different project.

Note: pb project target will change the namespace of the kubectl current context. All kubectl commands will now utilize the targeted project’s namespace.

Adding and Removing Project Members

Any member of a project can add and remove other project members.

Adding Users to a Project

To add users to a project:

  1. Target your project.

  2. Run:

    pb project user add USERNAME
    

    Where USERNAME is the username of the user you want to add.

Removing Users from a Project

To remove users from a project:

  1. Target your project.

  2. Run:

    pb project user remove USERNAME
    

    Where USERNAME is the username of the user you want to remove.

Adding Groups to a Project

To add groups to a project:

  1. Target your project.

  2. Run:

    pb project group add GROUPNAME
    

    Where GROUPNAME is the name of the group you want to add.

Removing Groups from a Project

To remove groups from a project:

  1. Target your project.

  2. Run:

    pb project group remove GROUPNAME
    

    Where GROUPNAME is the name of the group you want to remove.

Listing Members of a Project

To list members of a project:

  1. Target your project.

  2. Run:

    pb project members
    

Managing Image Registries for a Project

For a project to use an image registry in Build Service, you must associate an image registry and the image registry credentials with the project. If the source code for the image is saved in a repository, you must also associate the Git credentials with the project.

Build Service uses these credentials to deliver container image builds to the specified registry.

Note: The registry credentials must belong to a user with write access on the registry.

Build Service supports the following image registries:

  • Docker Hub
  • GCR
  • Harbor
  • Artifactory

Deleting a Project

This procedure describes how to delete a project using the pb CLI.

Warning: If you delete a project, all registry credentials and Git secrets associated with that project are also deleted.

To delete a project:

  1. Delete all image configurations in Build Service that are owned by the project. You cannot delete a project if the project owns any images on Build Service. To delete image configurations, see Delete an Image.

  2. Run:

    pb project delete PROJECT-NAME
    

    Where PROJECT-NAME is the name of the project to delete.

Managing Projects with kubectl

All projects are configured with a cluster scoped project Custom Resource.

apiVersion: projects.pivotal.io/v1alpha1
kind: Project
metadata:
   name: project-name
spec:
   access:
   - kind: User
     name: oidc:user-name
   - kind: Group
     name: oidc:group-name
  • name: The name of the project and the corresponding namespace
  • access: A list of subjects to provide access to the project.
  • access.[kind]: The kind of the subject, either User or Group.
  • name: The name the subject.

Note: If you are utilizing odic for identity, names may need to be prefixed with the odic prefix.