Skip to main content

Create and Manage Projects

A Project is a team workspace within a Tenant. Projects are where most day-to-day work happens; they give teams their own space, controlled access, and dedicated resources to build and run AI/ML applications and models.

A default Tenant and Project are automatically created when you install PaletteAI with global.featureFlags.systemDefaultResources: true in your Helm values. For production workloads, we recommend creating a separate Project per team, product, or business use case. This prevents teams from accidentally modifying AI/ML applications and models, as well as important configurations outside of their purview.

You can create Projects using the PaletteAI user interface (UI) or Kubernetes manifests.

UI Workflow

For teams preferring a guided visual experience, use the PaletteAI UI to create, modify, and delete Projects with step-by-step validation.

Create Project

Create a new Project to give your team a dedicated workspace with controlled access and isolated resources for building and deploying AI/ML applications and models.

Prerequisites

  • An existing Tenant.

  • A user with Tenant admin permissions for the Tenant the Project will belong to.

Enablement

  1. Log in to the PaletteAI Tenant the Project will belong to.

  2. From the Projects Menu in the top-left, select All Projects.

  3. From the left main menu, select Projects.

  4. In the top-right, select Create Project.

  5. Use the following table to enter Basic information about the Project. Select Next when finished.

    Basic Information
    ParameterDescriptionRequired
    Project nameThe Project display name. Only letters, numbers, and spaces are permitted.
    DescriptionA brief description of the Project.
    TagsKey-value pairs used to organize and filter Projects.
  6. To use the default Tenant Settings resource for this Project, proceed to the Next screen. To use a custom Settings resource for this Project instead of the default Tenant Settings, toggle the Define custom settings switch, select Add Palette integration, and provide the following information.

    Palette Integration
    ParameterDescriptionRequired
    Integration TypeThe infrastructure to deploy Compute Pools on. Only Palette is supported at this time. Refer to our Integrate with Palette guide to learn more about how Palette and PaletteAI work together to host your AI/ML applications and models.
    Integration NameThe name for this Palette integration. Each Palette integration name must be unique within the scope of the Project.
    Host URLThe endpoint of your Palette instance.
    TenantThe name of the Palette Tenant that contains the Palette Project to deploy Compute Pools on. This value is stored for display purposes in the Settings status and is not used for authentication or API calls.
    Project IDThe ID of your Palette Project to deploy Compute Pools on.
    Skip SSL Certificate VerificationDefaults to false. If true, the server's SSL certificate is not verified when making API calls to the host URL. Enable only for servers that use a self-signed SSL certificate.
    API KeyThe Palette API key that belongs to the Palette user under which Compute Pools will be deployed.
    Annotations(Reserved for future use) The Kubernetes annotations assigned to the Palette integration.
    Labels(Reserved for future use) The Kubernetes labels assigned to the Palette integration.

    Once all required information is entered, select Validate to test your Palette credentials. Once validated, Save your Palette integration. The integration appears on the Project settings screen. If any changes are needed, select Edit; otherwise, proceed to the Next screen.

  7. Use the Access control screen to map OpenID Connect (OIDC) groups to Project roles. At least one viewer, editor, and admin group is required per Project. Select Add group to add groups or the Delete icon to remove them. Proceed to the Next screen when finished.

    info

    The OIDC groups must match the groups from your identity provider (Azure AD, Okta, etc.). For static Dex users, these groups must be configured in the dexGroupMap in your Helm values. Refer to User Impersonation for additional information on configuring static Dex users.

  8. The Compute Config screen determines the default settings for all Compute Pools deployed through the Project. Select each menu item, making changes as necessary. Select Next when finished.

    Compute Config - General
    ParameterDescriptionRequired
    Compute Config NameThe name for this Compute Config resource. Each Compute Config name must be unique within the scope of the Project.
    Deletion PolicyChoose whether to Delete or Orphan the cluster in Palette when the Compute Pool is deleted in PaletteAI.

    - Delete - (default) Delete the cluster from Palette when you delete the Compute Pool in PaletteAI.
    - Orphan - Retain the cluster in Palette when you delete the Compute Pool in PaletteAI.
    SSH KeysAdd public Secure Shell (SSH) keys to allow users to access Compute Pool nodes via SSH.

    Compute Config - Edge Configuration
    ParameterDescriptionRequired
    VIPThe virtual IP (VIP) address used as the default control plane endpoint for Compute Pools deployed in this Project. The VIP cannot be in a Classless Inter-Domain Routing (CIDR) range that cannot be routed through a proxy. The address must be reachable from all nodes in the Compute Pool and cannot overlap with existing IP addresses in your network, including your Edge hosts.

    Note: Only one Compute Pool can use this VIP. Override the VIP when deploying additional Compute Pools.
    NTP ServersNetwork Time Protocol (NTP) servers used to synchronize time across all nodes in the Compute Pool.
    Enable Network OverlayCreates a virtual network on top of the physical network of the Compute Pool, allowing cluster components within the Compute Pool to communicate using stable, virtual IP addresses, regardless of underlying physical IP address changes. The fields in the following Compute Config - Enable Network Overlay table appear when you enable the overlay network.

    For more information on overlay networks, refer to Palette's Enable Network Overlay guide.

    Compute Config - Enable Network Overlay
    ParameterDescriptionRequired
    Enable Static IPUse an IP allocation type of static instead of Dynamic Host Configuration Protocol (DHCP) for the overlay VIP.
    CIDRThe CIDR range for the overlay network. The first IP address in the overlay CIDR range is used as the overlay VIP. This VIP is the internal overlay VIP used by the Compute Pool.
    Overlay Network TypeThe type of overlay network protocol to use. Only VXLAN is supported.

    Compute Config - Control Plane Defaults
    ParameterDescriptionRequired
    Node CountThe number of control plane nodes per Compute Pool. Choose 1, 3, or 5 nodes. If 1 is selected, Worker node eligible must be enabled.
    Worker node eligibleAllow AI/ML applications and models to be deployed on control plane nodes. If Node Count is 1, this option cannot be disabled.
    CPU CountThe total CPU cores required (requested) across all control plane nodes in the Compute Pool.
    ArchitectureThe architecture of the control plane nodes in the Compute Pool. Choose between AMD64 and ARM64.
    AnnotationsThe Kubernetes annotations assigned to each control plane node in the Compute Pool.
    LabelsThe Kubernetes labels assigned to each control plane node in the Compute Pool.
    TaintsThe Kubernetes taints assigned to each control plane node in the Compute Pool.

    Compute Config - Worker Pool Defaults
    ParameterDescriptionRequired
    AnnotationsThe Kubernetes annotations assigned to each worker node in the Compute Pool.
    LabelsThe Kubernetes labels assigned to each worker node in the Compute Pool.
  9. (Optional) Use the next screen to set GPU Limits and Requests across all Compute Pools deployed in this Project. The Key parameter defines the GPU family, whereas the Value parameter specifies the GPU limit. To set a GPU limit for all other GPU families that are not defined, enter Default in the Key field. Select Next when finished.

    For more information on GPU limits, refer to the Tenants and Projects concept page.

  10. Review your Project setup. Expand the Access Control, Compute Config, and Limits sections for additional details. If changes are required, use the Previous button to return to the applicable screen or select the appropriate step from the progress menu on the left side of the screen. If no changes are needed, select Submit to create the Project.

Validate

  1. Log in to PaletteAI as a Tenant or Project admin.

  2. Navigate to your Project using either of the following methods:

    • (Tenant or Project admin) From the Projects Menu, select your Project.
    • (Tenant admin) From the Projects Menu, select All Projects. Next, from the left main menu, select Projects. Your Project is visible as a tile. Select it to change to the Project scope.
  3. From the left main menu, select Project Settings.

  4. Navigate through the menu items on the left to verify all Project configurations are correct.

Modify Project

As your team's needs evolve, you can adjust Project configurations to grant new team members access, modify default Compute Pool settings, enforce GPU limits, or integrate with a different Palette instance.

Prerequisites

Enablement

  1. Log in to the PaletteAI Tenant the Project belongs to.

  2. Navigate to your Project using either of the following methods:

    • (Tenant or Project admin) From the Projects Menu, select your Project.
    • (Tenant admin only) From the Projects Menu, select All Projects. Next, from the left main menu, select Projects. Your Project is visible as a tile. Select it to change to the Project scope.
  3. From the left main menu, select Project Settings.

  4. Navigate through the menu items on the left. Here, you can modify existing project configurations, as well as create new ones or swap those currently in use.

    Menu ItemDescriptionAdditional Information
    GeneralModify the Project's display name, description, and tags.Basic Information
    Access controlMap OIDC groups to Project roles. At least one viewer, editor, and admin group is required per Project. Select Add group to add groups or the Delete icon to remove them.

    The OIDC groups must match the groups from your identity provider (Azure AD, Okta, etc.). For static Dex users, these groups must be configured in the dexGroupMap in your Helm values. Refer to User Impersonation for additional information on configuring static Dex users.
    Roles and Permissions
    ComputeView the list of control-plane- and worker-node-eligible Compute resources available for deploying Compute Pools and AI/ML applications and models. PaletteAI populates this list based on the Palette integration defined in the Settings and the Edge hosts with the appropriate tags.N/A
    Compute ConfigSelect the default Compute Config to use when deploying Compute Pools in this Project. Use the Create Compute Config button to create additional Compute Configs, which can be used to override the default Compute Config during Compute Pool creation. Use the three-dot menu to Edit or Delete existing Compute Configs.- Compute Config - General
    - Compute Config - Edge Configuration
    - Compute Config - Enable Network Overlay
    - Compute Config - Control Plane Defaults
    - Compute Config - Worker Pool Defaults
    LimitsSet GPU Limits and Requests across all Compute Pools deployed in this Project.Tenants and Projects
    Settings RefSelect the default Settings used to locate Compute resources. The title above the search bar indicates if the Settings resource is sourced from the Tenant or Project scope.

    To use a different Settings resource, select Create Project Settings or Change Settings Ref. To modify existing Project Settings, reference it as the default Settings resource, and use the three-dot menu to Edit the Settings. Tenant Settings cannot be modified at the Project scope, and all Settings must reference a Palette integration.
    Palette Integration

Validate

  1. Log in to PaletteAI as a Tenant or Project admin.

  2. Navigate to your Project using either of the following methods:

    • (Tenant or Project admin) From the Projects Menu, select your Project.
    • (Tenant admin) From the Projects Menu, select All Projects. Next, from the left main menu, select Projects. Your Project is visible as a tile. Select it to change to the Project scope.
  3. From the left main menu, select Project Settings.

  4. Navigate through the menu items on the left. Verify the your updated project configurations are displayed and set to default, where applicable.

Delete Project

If you no longer need a Project, you can remove it, along with all Project-scoped configurations, such as Compute Configs and Settings.

tip

To reuse certain Project configurations in another Project, change the namespace referenced in the resource's manifest to point to the other Project's namespace. For details, refer to the YAML Workflow - Delete Project section.

Prerequisites

  • A user with Tenant admin permissions for the Tenant the Project belongs to.

Enablement

  1. Log in to the PaletteAI Tenant the Project belongs to.

  2. From the Projects Menu in the top-left, select All Projects.

  3. From the left main menu, select Projects.

  4. Select the three-dot menu beside the applicable Project tile and Delete the Project.

Validate

  1. Log in to the PaletteAI Tenant the Project belongs to.

  2. From the Projects Menu in the top-left, select All Projects.

  3. From the left main menu, select Projects.

  4. Verify the applicable Project tile is no longer available.

Kubernetes Manifest Workflow

For automation, GitOps integration, or infrastructure-as-code workflows, use kubectl and Kubernetes manifests to create, modify, and delete Projects programmatically.

Create Project

To automate Project provisioning or integrate with GitOps workflows, create a new Project by applying Kubernetes manifests. This approach gives your team a dedicated workspace while enabling infrastructure-as-code practices.

Prerequisites

  • kubectl installed.

  • The KUBECONFIG environment variable set to the path of the PaletteAI hub cluster's kubeconfig file.

    export KUBECONFIG=<kubeconfig-location>
  • A Tenant namespace for the Tenant the Project will belong to.

Enablement

  1. Create a directory for the PaletteAI Project and navigate to the directory. Use this directory to consolidate all Project-scoped manifests.

    mkdir <project-name>
    cd <project-name>
  2. Create a Namespace resource for your Project. Use the following command to create a basic Namespace manifest with the required parameters.

    cat << EOF > namespace.yaml
    apiVersion: v1
    kind: Namespace
    metadata:
    name: <project-namespace>
    EOF
  3. Create a ComputeConfig resource that defines the default configurations to apply to nodes provisioned to Compute Pools. Use the following command to create a basic ComputeConfig manifest with the required parameters. Replace all placeholders with the necessary metadata and spec.paletteClusterConfig values.

    For a complete list of parameters, refer to the ComputeConfig resource spec.

    cat << EOF > compute-config.yaml
    apiVersion: spectrocloud.com/v1alpha1
    kind: ComputeConfig
    metadata:
    name: <compute-config-name>
    namespace: <project-namespace>
    spec:
    paletteClusterConfig:
    defaults:
    controlPlaneDefaults:
    nodeCount: <node-count>
    edge:
    vip: '<compute-pool-vip>'
    EOF
    ComputeConfig - metadata
    ParameterDescriptionExample Value
    nameThe name of the ComputeConfig resource. The ComputeConfig name must be unique within the Project namespace.edge-compute-config
    namespaceThe namespace under which to create ComputeConfig resource. The ComputeConfig must be created in the Project namespace.project-docs
    ComputeConfig - spec.paletteClusterConfig
    ParameterDescriptionExample Value
    defaults.controlPlaneDefaults.nodeCountThe number of control plane nodes deployed per Compute Pool. Must be 1, 3, or 5 to maintain quorum.1
    edge.vipThe VIP address used as the default control plane endpoint for Compute Pools deployed in this Project. The VIP cannot be in a CIDR range that cannot be routed through a proxy. The address must be reachable from all nodes in the Compute Pool and cannot overlap with existing IP addresses in your network, including your Edge hosts.

    Note: Only one Compute Pool can use this VIP. Override the VIP when deploying additional Compute Pools.
    10.10.189.24
  4. Create the Project resource. Use the following command to create a basic Project manifest with the required metadata and spec parameters.

    For a complete list of parameters, refer to the Project resource spec.

    cat << EOF > project.yaml
    apiVersion: spectrocloud.com/v1alpha1
    kind: Project
    metadata:
    name: <project-name>
    namespace: <project-namespace>
    spec:
    displayName: '<project-display-name>'
    tenantRef:
    name: '<tenant-name>'
    roleMapping:
    viewer:
    - '<viewer-role>'
    editor:
    - '<editor-role>'
    admin:
    - '<admin-role>'
    computeConfigRef:
    name: '<compute-config-name>'
    namespace: '<project-namespace>'
    EOF
    Project - metadata
    ParameterDescriptionExample Value
    nameThe name of the Project resource. The Project name must be unique within the Project namespace.project-docs
    namespaceThe namespace of the Project resource. The Project must be created in the Project namespace.project-docs
    Project - spec
    info

    The roleMapping groups must match the OIDC groups from your identity provider (Azure AD, Okta, etc.). For static Dex users, these groups must be configured in the dexGroupMap in your Helm values. Refer to User Impersonation for additional information on configuring static Dex users.

    ParameterDescriptionExample Value
    displayNameThe display name of your Project. This will be the name of the Project as viewed from the Projects Menu. Only letters, numbers, and spaces are permitted.Docs
    tenantRef.nameThe metadata.name of the Tenant resource the Project will belong to. For a list of all Tenant names, issue the command kubectl get tenants --all-namespaces.default
    roleMapping.viewerA list of OIDC groups with read-only access to all Project resources. At least one group is required.vision-read
    roleMapping.editorA list of OIDC groups that can deploy and manage AI/ML applications and models within the Project. At least one group is required.vision-write
    roleMapping.adminA list of OIDC groups with full control over all Project resources and configurations. At least one group is required.platform-admin
    computeConfigRef.nameThe metadata.name of the ComputeConfig resource created in the previous step.edge-compute-config
    computeConfigRef.namespaceThe metadata.namespace of the ComputeConfig created in the previous step. The ComputeConfig resource must be created in the Project namespace.project-docs
    info

    By default, the Project inherits the Tenant's Settings resource. To use a custom Settings resource for this Project instead of the default Tenant Settings, you must reference an existing Settings resource within the Project spec. The referenced Settings resource must be in the Project's namespace.

    spec:
    settingsRef:
    name: <settings-name>
  5. Create your PaletteAI Project and associated resources using the correct dependency order. Omit the Settings resource if using the default Tenant Settings.

    kubectl apply --filename namespace.yaml
    kubectl apply --filename settings.yaml
    kubectl apply --filename compute-config.yaml
    kubectl apply --filename project.yaml
    Example output
    namespace/project-docs created
    settings.spectrocloud.com/docs-settings created
    computeconfig.spectrocloud.com/edge-compute-config created
    project.spectrocloud.com/project-docs created

Validate

  1. Verify the Project's Namespace resource exists. In the following example, we created the namespace project-docs.

    kubectl get namespaces
    Example output
    NAME                                    STATUS   AGE
    # ... additional output omitted for readability
    open-cluster-management-hub Active 21d
    palette-system Active 21d
    piraeus-system Active 21d
    project-docs Active 19m
    spectro-mgmt-plane Active 21d
    spectro-system Active 21d
    spectro-task-693f654a6dd7fb8a0a2a6e3d Active 21d
    ui-system Active 21d
    zot-system Active 21d
  2. Verify the dependent resources exist.

    info

    If you created the Project referencing an alternate Settings resource, the SETTINGS column in the Project output is populated, and an additional Settings resource is created.

    kubectl get computeconfig,projects,settings --all-namespaces
    Example output
    NAMESPACE      NAME                                                 AGE
    default computeconfig.spectrocloud.com/default 21d
    project-docs computeconfig.spectrocloud.com/edge-compute-config 19m

    NAMESPACE NAME DISPLAYNAME READY TENANT SETTINGS COMPUTE CONFIG ROLES CREATED AGE
    default project.spectrocloud.com/default Default Project true default default true 21d
    project-docs project.spectrocloud.com/project-docs Docs true default docs-settings edge-compute-config true 19m

    NAMESPACE NAME READY AGE
    default settings.spectrocloud.com/default true 21d
    project-docs docs-settings true 19m
  3. Confirm a resource has the expected configuration.

    kubectl describe <resource-type> <resource-name> --namespace <project-namespace>

    The following example fetches the current status of the ComputeConfig resource. Note the values nodeCount: 1 and vip: 10.10.189.140.

    Example command
    kubectl describe computeconfig edge-compute-config --namespace project-docs
    Example output
    Name: edge-compute-config
    Namespace: project-docs
    Labels: <none>
    Annotations: <none>
    API Version: spectrocloud.com/v1alpha1
    Kind: ComputeConfig
    Metadata:
    Creation Timestamp: 2026-01-06T15:26:04Z
    Finalizers: spectrocloud.com/computeconfig-finalizer
    Generation: 1
    Resource Version: 20819572
    UID: 6bf27d65-b998-4503-923a-34ef602814d6
    Spec:
    Palette Cluster Config:
    Defaults:
    Control Plane Defaults:
    Architecture: AMD64
    Node Count: 1
    Single Node Cluster: false
    Worker Node Eligible: false
    Deletion Policy: delete
    Edge:
    Vip: 10.10.189.140
    Events: <none>

Modify Project

To update Project configurations programmatically or track changes in version control, modify the relevant Kubernetes manifests and apply your changes with kubectl apply.

Prerequisites

  • kubectl installed.

  • The KUBECONFIG environment variable set to the path of the PaletteAI hub cluster's kubeconfig file.

    export KUBECONFIG=<kubeconfig-location>
  • A text editor to modify existing manifests. This example uses Vi.

Enablement

  1. Open the applicable resource manifest using an editor of your choice and make any necessary changes.

    Use the following table for an overview of changes you can make to required parameters for different resources. For a complete list of parameters per resource, refer to the applicable Resource page.

    ResourceModificationsAdditional Information
    ProjectUpdate displayName, description, tags, and roleMapping groups to modify basic information and access control. Update the Project's gpuResources to modify GPU limits and requests across all Compute Pools.- Project - metadata
    - Project - spec
    - Tenants and Projects - GPU Quotas
    ComputeConfigUpdate paletteClusterConfig to modify Edge host configuration, control plane defaults, and worker pool defaults. Create additional ComputeConfig resources and update the Project's default computeConfigRef.- ComputeConfig - metadata
    - ComputeConfig - spec.paletteClusterConfig
    SettingsCreate a new Settings resource in the Project namespace and update the Project's settingsRef to use custom Palette integration Settings.Settings

    In this example, we used Vi to modify the nodeCount from 1 to 3 and the vip from 10.10.189.140 to 10.10.189.200.

    vi compute-config.yaml
    Updated ComputeConfig
    apiVersion: spectrocloud.com/v1alpha1
    kind: ComputeConfig
    metadata:
    name: edge-compute-config
    namespace: project-docs
    spec:
    paletteClusterConfig:
    defaults:
    controlPlaneDefaults:
    nodeCount: 3
    edge:
    vip: '10.10.189.200'
  2. When you are finished, save the file and apply your changes.

    kubectl apply --filename <manifest-location>
    Example command
    kubectl apply --filename compute-config.yaml

Validate

Verify your changes were applied by inspecting the updated resource.

kubectl describe <resource-type> <resource-name> --namespace <project-namespace>

The following example verifies the ComputeConfig was modified with the new values of nodeCount: 3 and vip: 10.10.189.200.

Example command
kubectl describe computeconfig edge-compute-config --namespace project-docs
Example output
Name: edge-compute-config
Namespace: project-docs
Labels: <none>
Annotations: <none>
API Version: spectrocloud.com/v1alpha1
Kind: ComputeConfig
Metadata:
Creation Timestamp: 2026-01-06T15:26:04Z
Finalizers: spectrocloud.com/computeconfig-finalizer
Generation: 2
Resource Version: 21630027
UID: 6bf27d65-b998-4503-923a-34ef602814d6
Spec:
Palette Cluster Config:
Defaults:
Control Plane Defaults:
Architecture: AMD64
Node Count: 3
Single Node Cluster: false
Worker Node Eligible: false
Deletion Policy: delete
Edge:
Vip: 10.10.189.200
Events: <none>

Delete Project

If you no longer need a Project, remove it by deleting its namespace. This cascades deletion to all Project-scoped resources, such as Compute Configs and Settings.

Prerequisites

  • kubectl installed.

  • The KUBECONFIG environment variable set to the path of the PaletteAI hub cluster's kubeconfig file.

    export KUBECONFIG=<kubeconfig-location>

Enablement

To delete the Project and all resources within the Project, such as the Project's Compute Config, delete the Project's Namespace resource.

kubectl delete --filename <namespace-location>
Example command
kubectl delete --filename namespace.yaml

If you do not have access to the Namespace manifest, delete the Namespace resource directly.

kubectl delete namespace <project-namespace>
Example command
kubectl delete namespace project-docs
tip

After you delete the Project's namespace, you can migrate existing resources to other Projects. For example, to migrate a ComputeConfig resource, change the namespace referenced in metadata.namespace to the alternate Project's namespace, and apply your changes with kubectl apply --filename <manifest-location>.

apiVersion: spectrocloud.com/v1alpha1
kind: ComputeConfig
metadata:
name: edge-compute-config
namespace: <other-project-namespace>
spec:
paletteClusterConfig:
defaults:
controlPlaneDefaults:
nodeCount: 3
edge:
vip: "10.10.189.200"

Validate

  1. Verify the Project's namespace no longer exists. In the following example, we removed the namespace project-docs.

    kubectl get namespaces
    Example output
    NAME                                    STATUS   AGE
    # ... additional output omitted for readability
    open-cluster-management-hub Active 21d
    palette-system Active 21d
    piraeus-system Active 21d
    spectro-mgmt-plane Active 21d
    spectro-system Active 21d
    spectro-task-693f654a6dd7fb8a0a2a6e3d Active 21d
    ui-system Active 21d
    zot-system Active 21d
  2. Verify the dependent resources no longer exist. In the following example, the ComputeConfig, Project, and Settings resources for the project-docs namespace were removed as a result of deleting the Namespace resource.

    Example output
    kubectl get computeconfig,projects,settings --all-namespaces
    Example output
    NAMESPACE      NAME                                    AGE
    default computeconfig.spectrocloud.com/default 21d

    NAMESPACE NAME DISPLAYNAME READY TENANT SETTINGS COMPUTE CONFIG ROLES CREATED AGE
    default project.spectrocloud.com/default Default Project true default default true 21d

    NAMESPACE NAME READY AGE
    default settings.spectrocloud.com/default true 21d

Next Steps

Once you have a Project, you can create or import a Profile Bundle. Profile Bundles are used to configure reusable infrastructure stacks for Compute Pools and application stacks for App Deployments.