Projects

Some deployments are very large, running on more than 10,000 hosts. Other deployments must be compartmentalized, for regulatory or operational reasons. Projects solve two problems: Scale and multi-tenancy.
Projects let you deploy a single master Console, with a single URL, that can scale out to support an infinite number of container hosts. You can set up an environment that shares the same rules and configurations as the master Console, or deploy separate compartmentalized environments which operate independently with their own rules and configurations.
For example, you might have https://console.customer.com as the single URL for accessing the Console UI and API. Then you could deploy a Console to each of your regional data centers to support a scaled-out production environment, or segregated instances of Console for each business unit, or both, and manage all of them from a single Central Console.
Role-based access control (RBAC) rules manage who can access which project. When users log onto Prisma Cloud Central Console, they are shown a list of projects to which they have access and can switch between them.

Terminology

The following terms are used throughout this article:
  • Central Console
    --
    Also known as the master Console or just master. This is the interface from which administrators manage (create, access, and delete) their projects.
  • Supervisor
    --
    Secondary, slave Console responsible for the operation of a project. Supervisor Consoles are headless. Their UI and API are not directly accessible. Instead, users interact with a project from Central Console’s UI and API.
  • Project
    --
    A deployment unit that consists of a Supervisor Console and up to 5,000 Defenders. There are two types of projects: scale projects and tenant projects.
  • Scale project
    --
    The Supervisor Console inherits all rules and settings from the Central Console. Stack multiple scale projects together to deploy Prisma Cloud to large environments with a large number of hosts. Each scale project supports 5,000 Defenders. Two scale projects can support and environment with 10,000 hosts, three scale projects supports 15,000 hosts, and so on.
  • Tenant project
    --
    Tenant projects maintain all their own rules and settings, separate from Central Console and any other Supervisor Consoles.

When to use projects

Carefully assess whether you need projects. Provisioning projects when they are not required will needlessly complicate the operation and administration of your environment.
1. Does your container environment have more than 5,000 hosts?
If yes, then provision a scale project, where each scale project can handle a maximum of 5,000 hosts (Defenders). Add a scale project for every 5,000 hosts in your environments. Stacked scale projects work together as a single, cohesive environment with shared rules and settings.
If your environment has fewer than 5,000 hosts, then you do not need to provision any scale projects. A single Console will be sufficient for your needs. You can always migrate to a project structure if your environment does grow past 5,000 hosts. For more information, see Migration strategies.
2. Do you have multiple segregated environments, where each environment must be configured with its own rules and policies?
If yes, then deploy a tenant project for each environment.
3. Are you upgrading from Prisma Cloud 2.3?
If yes, then your existing deployment will continue to work exactly as it did before.
Migrating to projects is not required. Projects are an optional feature that is disabled by default. There is no need to migrate to projects unless you have a specific need for the functionality it offers.
If you are using Prisma Cloud 2.3, and you’ve deployed multiple Consoles, you can easily adopt projects to fold your stand-alone Consoles under the management of a single Central Console. First upgrade all your Consoles to Twistock 2.4, then see Migration strategies.
4. If you choose not to use projects now, can you migrate to projects at a later time?
Yes. Even if you choose not to use projects now, you’re not locked into that decision. You can always migrate to projects at a later time.

Architecture

Projects federate the UI and API for multiple Consoles.
For example, if you have three separate instances of Consoles for development, test, and production environments, projects let you manage all of them from a single Central Console. With projects, one Console is designated as the master and all others are designated as supervisors. Thereafter, all UI and API requests for a project are proxied through the master and routed to the relevant supervisor. Supervisors do not serve a UI or API.
A single Central Console can support both scale and tenant projects simultaneously.

Connectivity

By default, the master and its supervisor Consoles communicate over port 8083. You can configure a different port by setting MANAGEMENT_PORT_HTTPS in
twistlock.cfg
at install time. All Consoles must use the same value for MANAGEMENT_PORT_HTTPS. Communication between the master and supervisor Consoles must be direct, and cannot be routed through a proxy.
Defenders communicate with their respective supervisor Consoles. Project Defenders never communicate directly with the Central Console.
Prisma Cloud CA signed certs are used for establishing the Central Console to Supervisor Console communication link. Since no user interacts with the Supervisor Console directly, the link is an internal architectural detail, and we use our own CA. This setup reduces the risk of outages due to expired certs.
When configuring Central and Supervisor Consoles, you must configure the Supervisor Console to include the Subject Alternative Name (SAN) for the Central Console.
When configuring access to the Consoles via Ingress Network Routes in Kubernetes, you must add the Central Console to the Supervisor Console Ingress configuration.
Central Console can have its own set of Defenders. In this case, these Defenders do communicate directly with Central Console. However, no project Defenders ever communicate directly with Central Console.

Multi-tenancy

Tenant projects are like silos. They each have their own rules and settings that are created and maintained separately from all other projects.

Infinite scale

Each project can support a maximum of 5,000 Defenders. Scale projects can be stacked to support very large environments (greater than 5,000 hosts). For example, if your your container environment runs 10,000 hosts, then you would deploy 2 scale projects.
Data for each project is maintained with each supervisor. Data includes such things as audit event records and image scan reports. This division of data is what helps enable infinite horizontal scale. Even though two scale projects might share the same rules and settings, they will have their own audits, container scan reports, and so on.
Inherited rules and settings for scale projects
Scale projects inherit all rules and almost all configurations from the Central Console.
Rules and settings are distributed to supervisor Consoles by way of their REST APIs. All scale projects are updated in parallel. The Central Console queries the existing policies and settings in the supervisor Consoles. If the local policies and settings are different than the remote policies and settings, they are updated using the supervisor’s REST API.
Rules and configurations are distributed to supervisor Consoles when:
  • A supervisor Console becomes available (on connect or reconnect).
  • A rule or setting changes in the Central Console.
For scale projects, requests for the settings pages and policies pages will return data from the master project.
Scale projects inherit almost all rules from Central Console:
  • Defend > Firewalls > {CNAF, CNNF}
  • Defend > Runtime > {Container Policy, Host Policy}
  • Defend > Vulnerabilities > Policy
  • Defend > Compliance > {Policy, Trusted Images}
Scale projects inherit the following settings from Central Console:
  • Manage > Collections
  • Manage > System > Scan
    (Scan settings)
  • Manage > System > Proxy
    (Proxy settings)
  • Manage > System > Logging
  • Manage > System > Custom Feeds
  • Manage > System > Forensics
  • Manage > System > Intelligence
The settings under
Defend > Vulnerabilities > {Registry, Serverless}
and
Manage > Alerts
are not shared between scale projects.

Access control

When users log into Prisma Cloud Console, they are presented with a list of projects to which they have access, and they can chose the project they want to work in. Access to projects is controlled by role-based access control rules.
You can grant access to specific projects for any 'local' users created in Console under
Manage > Authentication > Users
. If you have integrated Console with an OpenLDAP, Active Directory, or SAML provider, you can grant access to projects by group. Users and groups can be granted access to multiple projects.
A user’s role is applied globally across all projects. That is, a user will have the same role for each project for which he has been granted access.
Rules and settings in scale projects can only be modified by a users with access to Central Console. If you are granted access to a scale project, but not Central Console, you’ll get an error when you try to create a new rule or change a setting. New rules and settings must be made in Central Console.
Project access control rules at the user level take precedence over access control granted at the group level. For example, if a 'local' user has been granted access to project1, but also belongs to group1, which has been granted access to project2, he will only have permissions to access project1.

Secrets

Prisma Cloud fully supports secrets management for tenant projects. Secrets management can be independently configured and managed for each tenant project.
For scale projects, secrets management is supported in Central Console only. Secrets are not propagated from Central Console to any connected scale projects.

Limitations

Moving Defenders between projects is not supported. To "move" a Defender, decommission it one project and install it in another.

Provisioning flow

Let’s look at how projects are provisioned.
Step 1:
Install Console using any installation method. For example, you could install Console (onebox) with the or as a service in a Kubernetes cluster. When Console is installed, it runs in master mode by default.
Step 2:
Install a second Console on a different host. By default, it also runs in master mode.
Step 3:
In the UI for Console 1, provision a new project. Specify the URL to Console 2 and the project type (tenant or scale). The provisioning process automatically changes the operating mode for Console 2 to supervisor. The UI and API for Console 2 are now no longer directly accessible.
Step 4:
The only difference between a master Console and a supervisor Console is whether its UI and API can be accessed directly, or whether it is proxied through the master. Assume you provisioned a tenant project in Step 3. To view your tenant project (managed by Console 2), open Console 1 and select the project. All your rules and settings for your project are loaded and displayed in Console 1.
You can release a supervisor, and return it to its original state by deleting the project. The supervisor Console reverts back to master mode.

Migration strategies

If you have already deployed one or more stand-alone Consoles, and you want to adopt a project-based structure, then the migration is easy. Simply designate one Console as master, then designate each remaining Console as a supervisor by provisioning projects for them.
Adding an existing Console to a project is not a destructive operation. All data is preserved, and the process can be reversed. The only thing that changes is the way you access Console when it is retooled as a supervisor. Supervisor Consoles cannot be accessed directly. They can only be accessed through the master Console, by selecting the project from
Selected project
drop down list.
For example, assume you’ve deployed three separate stand-alone Consoles: one for your production environment, one for your test environment, and one for your development environment.
When migrating to projects, you have the following options:
Option 1:
Promote one Console to master, and designate the others as supervisors. In this example, you pick the prod Console to be master, then create tenant projects for the test and development Consoles.
By default, Consoles run in master mode when they are installed, so you don’t need to do anything to "promote" prod to master. To relegate test and dev to supervisor, provision a project for each one.
Option 2:
Install a new Console on a dedicated host and designate it as master. Provision a tenant project for each of the prod, test, and dev Consoles.

Accessing the API

All API requests should be routed to Central Console only. Central Console checks if the client has the correct permissions to access the given project, and then:
  • For tenant projects, Central Console redirects the request to right supervisor, and then returns to supervisor’s response to the client.
  • For scale projects, Central Console responds directly to requests for rules and settings. For other data, such as audits and scan reports, you must specify the project in the API request.
For API requests that create, modify, or delete data, Central Console responds to the client with a success return code, and then updates the supervisor asynchronously.
To target an API request to a specific project, append the
project=
query parameter to your request. For example, to get a list of Defenders deployed in the prod project:
GET http://<CENTRAL-CONSOLE>:8083/api/v1/defenders?project=prod
Central Console reroutes the request to the appropriate supervisor. Not all requests need to be rerouted. For example, the endpoints for getting a list of users, groups, or projects are all handled by Central Console directly. Some endpoints require no special permissions to access them, such as getting a list projects to which a user has been granted access.

Provisioning a project

Provision new projects from the Central Console UI.
Communication between the master and supervisor Consoles must be direct, and cannot be routed through a proxy.
  1. Install a Console on a host in your environment using any install procedure.
    There is no need to create an admin user or enter your license. Those details will be handled for you in the provisioning phase of this procedure.
  2. Register the newly installed Console with the Central Console and create a project.
  3. Go to
    Manage > Projects > Manage
  4. Set
    Use Projects
    to
    On
    .
  5. Click on the
    Provision
    tab.
  6. Under
    Select Project type
    , choose
    Tenant
    or
    Scale
    .
  7. In
    Project name
    , give your project a name.
  8. In
    Supervisor address
    , enter the URL for accessing Console Include both the protocol (https://) and port.
  9. For a fresh Console install, there is no need to enter any credentials. They will be created for you automatically.
    If you are migrating an existing Console to a project, specify the admin credentials.

Decommissioning a project

Decommissioning a project simply reverts the supervisor Console back to a stand-alone master Console. The link between Central Console and the former supervisor Console is severed. All project data (rules, audits, scan reports) is left in tact.
When a project is created, the Console is configured with an admin user. When you delete the project, the admin credentials are shown to you so that you can continue to access and administer it. The credentials are shown only one time, so copy them and set them aside in a safe place.
  1. Open Central Console.
  2. Go to
    Manage > Projects > Manage
    .
  3. In the
    Provisioned Projects
    table, click delete on the project you want to delete.

Decommissioning disconnected projects

Central Console lets you delete projects, even if the supervisor Console is disconnected. The project is deleted from the master’s database, but it leaves the supervisor Console in the wrong state.
When you delete a disconnected project, Prisma Cloud tells you that the supervisor cannot be reached. To manually revert the supervisor Console back to a stand-alone master Console, call the supervisor’s REST API to change its settings.
  1. Decide how you want to access the supervisor’s REST API. You can use basic auth or an auth token.
  2. Update the supervisor’s project settings. The following example command uses basic auth. Only admin users are permitted to change project settings.
    $ curl -k \ -u <USER> \ -X POST \ -H 'Content-Type:application/json' \ -d '{"master":false, "redirectURL":""}' \ https://<SUPERVISOR-CONSOLE>:8083/api/v1/settings/projects

Deploying Defender DaemonSets for Projects (Console UI)

When creating a DaemonSet for a project, you can use the Console UI, twistcli, or Prisma Cloud API.
  1. In Console, use the drop-down menu at the top right of the UI to select the project where you want to deploy your DaemonSet.
  2. Go to
    Manage > Defenders > Deploy Daemon Set
    .
  3. Configure the deployment parameters, then copy and run the resulting install script.

Deploying Defender DaemonSets for Projects (twistcli)

Create a DaemonSet deployment file with twistcli. Specify both the project name and the DNS name or IP address of the Supervisor Console to which the DaemonSet Defenders will connect. The DNS name or IP address must be a Subject Alternative Name in the Supervisor Console’s certificate.
$ <PLATFORM>/twistcli defender export kubernetes \ --address https://<CENTRAL-CONSOLE>:8083 \ --project <PROJECT-NAME> --user <USER> \ --cluster-address <SUPERVISOR-CONSOLE-SAN>

Deploying Defender DaemonSets for Projects (Prisma Cloud API)

A DaemonSet deployment file can also be created with the API. Specify both the project name and the DNS name or IP address of the Supervisor Console to which the DaemonSet Defenders will connect. The DNS name or IP address must be a Subject Alternative Name in the Supervisor Console’s certificate.
$ curl -k \ -u <USER> -X GET \ 'https://<CENTRAL-CONSOLE>:8083/api/v1/defenders/daemonset.yaml?consoleaddr=<SUPERVISOR_CONSOLE_SAN>&listener=none&namespace=twistlock&orchestration=kubernetes&privileged=true&serviceaccounts=true&project=<PROJECT_NAME>'

Limitations

A few features aren’t supported when Projects is enabled. Many of these will be fully enabled for Projects in an upcoming release.

Assigned collections

Assigned collections aren’t supported when Projects is enabled. The UI prevents you from assigning collection permissions to users and groups when Projects is enabled. If you already have Assigned Collections before enabling Projects, the UI prevents you from enabling Projects in
Manage > Projects
. Collections without assigned users or groups are permitted when Projects is enabled.

CNNF

CNNF is supported in tenant projects only. It’s not supported in scale projects. Although the CNNF tab is displayed in Central Console, an error is displayed if you try to enable CNNF when a scale project exists.

Custom compliance rules

Custom compliance rules are supported in tenant projects only. They aren’t supported in scale projects. The UI blocks editing custom compliance rules in Central Console when a scale project exists.

Custom runtime rules

Custom runtime rules are supported in tenant projects only. They aren’t supported in scale projects. The UI blocks editing custom runtime rules in Central Console when a scale project exists.

Kubernetes audits

Kubernetes audit policies are supported in tenant projects only. It’s not supported in scale projects.

Secrets

Prisma Cloud fully supports secrets management for tenant projects. Secrets management can be independently configured and managed for each tenant project.
For scale projects, secrets management is supported in Central Console only. Secrets are not propagated from Central Console to any connected scale projects.

Trusted images

Trusted images are supported in tenant projects only. It’s not supported in scale projects. An error is displayed if you try to save a trusted images rule in Central Console when a scale project exists.

Type-ahead support during rule creation

Auto-complete for resource targeting during rule creation is supported in tenant projects only. It’s not supported in scale projects. Only resources connected to the Central Console are supported with type-ahead functionality. The resources under scale projects are not visible for type-ahead.

Recommended For You