Configure Integrations

A Settings resource holds the integrations PaletteAI uses to provision infrastructure and govern artificial intelligence and machine learning (AI/ML) workloads. This page shows how to configure each integration type and how to govern model availability through Project Model Settings.

The same workflow applies whether you configure integrations at the Tenant scope or the Project scope. Tenant admins create Tenant-level Settings in the Tenant namespace; Project admins create Project-level Settings in the Project namespace. The only difference is the namespace where the Settings resource and its Secrets reside.

For the Settings resource lifecycle, namespace rules, and inheritance behavior, refer to Configure Settings. For an overview of integrations and how they fit into PaletteAI, refer to the Settings and Integrations concept page.

Prerequisites

Before you configure an integration, ensure you have the following:

A Settings resource in the Tenant or Project namespace where the integration applies. Refer to Configure Settings to create one.
Permission to create Secrets and update the Settings resource in the target namespace.
For the Palette integration, a Palette API key, the Palette tenant name, the Palette host URL, and the default Palette project ID. Refer to Integrate with Palette for the Palette-side prerequisites.
For the Hugging Face integration, a Hugging Face Hub API token with at least read access.
For the NVIDIA NGC integration, an NVIDIA NGC API key.

Configure the Palette Integration

The Palette integration connects PaletteAI to the Spectro Cloud Palette platform. PaletteAI uses Palette as its infrastructure provider to deploy and manage the Kubernetes clusters that host your applications. Any Project that deploys Compute Pools must reference a Settings resource with a Palette integration.

Create the Palette Secret

The Palette integration stores its configuration in a single Secret with a palette key whose value is a JSON document.

Palette Secret
apiVersion: v1
kind: Secret
metadata:
  name: dev-settings-palette-secret
  namespace: primary-dev
type: Opaque
stringData:
  palette: |
    {
      "hostUrl": "<palette-host-url>",
      "apiKey": "<palette-api-key>",
      "tenant": "<palette-tenant-name>",
      "defaultProjectID": "<palette-default-project-id>"
    }

The JSON document supports the following fields.

Field	Description	Required
`apiKey`	API key for the Palette tenant.	✅
`defaultProjectID`	Default Palette project ID.	✅
`hostUrl`	Palette API URL.	✅
`tenant`	Palette tenant name.	✅
`skipSSLCertificateVerification`	If `true`, the server's SSL certificate is not verified. Defaults to `false`.	❌
`tlsSecretRef`	Name of a Kubernetes Secret in the same namespace that contains a `ca.crt` key with a PEM-encoded Certificate Authority (CA) certificate. Provides a custom CA when Palette uses a self-signed SSL certificate.	❌

warning

Leave skipSSLCertificateVerification disabled in production. When enabled, all API calls to Palette skip SSL certificate verification, which is acceptable for demonstration or experimentation but exposes production traffic. Use a valid SSL certificate signed by a trusted CA, or provide a custom CA certificate through tlsSecretRef. Refer to Custom CA Certificates for the configuration steps.

Reference the Palette Secret from the Settings Resource

Update the Settings resource to reference the Palette Secret. The palette integration takes both name and namespace, and the namespace must match the Settings resource's namespace.

Settings with Palette integration
apiVersion: spectrocloud.com/v1alpha1
kind: Settings
metadata:
  name: dev-settings
  namespace: primary-dev
spec:
  integrations:
    palette:
      name: dev-settings-palette-secret
      namespace: primary-dev

Configure the Hugging Face Integration

The Hugging Face integration provides API access to the Hugging Face Hub, allowing PaletteAI to fetch model metadata and download model artifacts. Adding a Hugging Face integration unlocks Hugging Face model governance through the Project's Model Settings.

Create the Hugging Face Secret

The Hugging Face integration references a Secret that holds the API token under a key you choose.

Hugging Face Secret
apiVersion: v1
kind: Secret
metadata:
  name: huggingface-token
  namespace: primary-dev
type: Opaque
stringData:
  token: <huggingface-token>

Reference the Hugging Face Secret from the Settings Resource

The Settings resource references the Secret through spec.integrations.huggingFace.apiKey. The reference uses both name and key. The Secret must reside in the same namespace as the Settings resource.

Settings with Hugging Face integration
apiVersion: spectrocloud.com/v1alpha1
kind: Settings
metadata:
  name: dev-settings
  namespace: primary-dev
spec:
  integrations:
    palette:
      name: dev-settings-palette-secret
      namespace: primary-dev
    huggingFace:
      apiKey:
        name: huggingface-token
        key: token

info

The key name is configurable through apiKey.key, but the PaletteAI UI creates Hugging Face Secrets with the key token. Use token to keep the YAML and UI paths interchangeable.

Configure the NVIDIA NGC Integration

The NVIDIA NGC integration provides credentials for pulling NVIDIA Inference Microservices (NIMs) from the NVIDIA NGC registry. Adding an NVIDIA NGC integration unlocks per-Project governance for the NIMs your teams can deploy.

Create the NVIDIA NGC Secret

The NVIDIA NGC integration uses a kubernetes.io/dockerconfigjson Secret. The same Secret authenticates to NGC for metadata access and serves as the pod image pull secret.

NVIDIA NGC Secret
apiVersion: v1
kind: Secret
metadata:
  name: nvidia-ngc
  namespace: primary-dev
type: kubernetes.io/dockerconfigjson
stringData:
  .dockerconfigjson: |
    {
      "auths": {
        "nvcr.io": {
          "username": "$oauthtoken",
          "password": "<ngc-api-key>"
        }
      }
    }

The literal $oauthtoken username is required by the NVIDIA NGC registry, not by PaletteAI.

Reference the NVIDIA NGC Secret from the Settings Resource

In the Settings resource, point both apiKey and imagePullSecret at the NGC Secret. PaletteAI uses the same Secret for both metadata access and as the pod image pull Secret.

Settings with NVIDIA NGC integration
apiVersion: spectrocloud.com/v1alpha1
kind: Settings
metadata:
  name: dev-settings
  namespace: primary-dev
spec:
  integrations:
    palette:
      name: dev-settings-palette-secret
      namespace: primary-dev
    nvidia:
      ngc:
        apiKey:
          name: nvidia-ngc
          key: .dockerconfigjson
        imagePullSecret:
          name: nvidia-ngc

info

apiKey.key and the Secret type are configurable, but the PaletteAI UI creates NVIDIA NGC Secrets with type kubernetes.io/dockerconfigjson and key .dockerconfigjson. Use these defaults to keep the YAML and UI paths interchangeable, and so the same Secret can function as a pod image pull secret downstream.

Configure Project Model Settings

Hugging Face and NVIDIA NGC integrations unlock per-Project model governance through the Project resource's modelSettings field. Through Model Settings, Project admins decide which models are available within a Project, independent of which integrations are configured at the Tenant level.

Model Settings cover two concepts:

Allow and disallow lists — for each integration enabled on a Project, define which model repositories or NIMs are allowed, which are denied, or both. A common pattern is to allow everything from a registry except a specific organization or tag.
Profile Bundle mappings — map model attributes to a Profile Bundle so PaletteAI automatically selects the correct Workload Profile for a given model source.

Project with Model Settings
apiVersion: spectrocloud.com/v1alpha1
kind: Project
metadata:
  name: primary-dev
  namespace: primary-dev
spec:
  displayName: Primary Dev
  tenantRef:
    name: my-tenant
  settingsRef:
    name: dev-settings
  computeConfigRef:
    name: dev-compute-config
    namespace: primary-dev
  roleMapping:
    viewer:
      - palette-ai-viewers
    editor:
      - palette-ai-editors
    admin:
      - palette-ai-admins
  modelSettings:
    huggingFace:
      enabled: true
      modelRepositoryACL:
        allow:
          - meta-llama/Llama-3.1-8B-Instruct
          - mistralai/Mistral-7B-Instruct-v0.3
        disallow:
          - '*'
    nvidia:
      ngc:
        enabled: true
        nimsACL:
          allow:
            - 'nvcr.io/nim/meta/llama-3.1-8b-instruct:1.3.3'
          disallow:
            - '*'
    profileBundleMappings:
      - source: HuggingFace
        sourceFilters:
          app: vllm
        profileBundleSelector:
          profilebundlename: vllm-profile-bundle
      - source: NGC
        sourceFilters:
          nims: 'true'
        profileBundleSelector:
          profilebundlename: ngc-nim-profile-bundle

The source field accepts the values HuggingFace and NGC. The profileBundleSelector field uses the literal lowercase key profilebundlename; the value is the Profile Bundle's metadata.name. The Profile Bundle must live in the Project's namespace.

For the full schema, refer to the Project Custom Resource Definition (CRD) reference.

Validation Constraints

The following constraints are enforced by the PaletteAI admission webhook. Configuration that violates any constraint is rejected at create or update time.

Constraint	Applies to	Reason
Integration Secrets must reside in the same namespace as the Settings resource	All integration Secrets	Ensures secret resolution is unambiguous and credentials are isolated per scope
Each integration Secret can be referenced by only one Settings resource per namespace	Palette, Hugging Face, NVIDIA NGC	Allows PaletteAI to safely delete the Secret automatically when the owning Settings is deleted
Palette Secret content must be unique across Settings resources	Palette	Prevents two Settings from sharing identical Palette credentials
`Project.metadata.name` must equal `Project.metadata.namespace`	Project resource	Required by the Project webhook
`Project.spec.computeConfigRef.namespace` must be the Project's namespace or the owning Tenant's namespace	Project resource	Limits Compute Config references to scopes the Project can access
`Project.spec.roleMapping.viewer`, `.editor`, and `.admin` each require at least one OpenID Connect (OIDC) group	Project resource	Ensures every Project tier has at least one binding

Next Steps

After you configure your integrations, refer to the following resources for related Project administration tasks:

Configure Settings — Settings lifecycle, inheritance, and Secret ownership rules
Create and Manage Projects — Project creation, role mapping, and quotas
Settings and Integrations — concept-level overview of integrations and Model Settings

Prerequisites​

Configure the Palette Integration​

Create the Palette Secret​

Reference the Palette Secret from the Settings Resource​

Configure the Hugging Face Integration​

Create the Hugging Face Secret​

Reference the Hugging Face Secret from the Settings Resource​

Configure the NVIDIA NGC Integration​

Create the NVIDIA NGC Secret​

Reference the NVIDIA NGC Secret from the Settings Resource​

Configure Project Model Settings​

Validation Constraints​

Next Steps​