Import a Cluster

When importing a cluster into Palette, you can select the mode you want Palette to use when managing the cluster. You can choose between read-only mode or full permission mode. Refer to Imported Clusters to learn more about each mode.

Full Permission Mode

Full permission mode grants the Palette agent broad Role-Based Access Control (RBAC) permissions to your cluster. This enables Day-2 operations such as deploying add-on profiles, configuring RBAC bindings and namespaces, running compliance scans, and scheduling backups. The agent also automatically installs a metrics server if one is not already present on the cluster.

warning

Deploying add-on cluster profiles on imported clusters with the Generic cloud type requires Palette 4.9.41 or later. On earlier versions, the cluster with the add-on profile imports successfully and continues to report health, cost, and event data, but packs are never applied. Clusters imported as AWS IaaS, Azure IaaS, or GCP IaaS are not affected on any version.

Prerequisites

• Your imported cluster must meet the following requirements:

  • Use Kubernetes version 1.19.x or later.
  • Have network access to Palette SaaS or your self-hosted Palette instance.
  • Have cluster-admin permissions.

• Your local workstation must have kubectl installed and configured to access your imported cluster.

Import a Cluster

1. Log in to Palette.

2. From the left main menu, select Clusters.

3. Choose Import Cluster.

4. On the Import Cluster page, complete the following information as applicable. The fields vary depending on the Cloud Type selected.

   Field	Description	Cloud Type
   Cluster Name	A unique display name for the cluster you want to import.	All
   Cloud Type	The infrastructure environment your cluster resides in. The cloud type determines what infrastructure metadata Palette displays. Supported options include AWS IaaS, Azure IaaS, GCP IaaS, and Generic. Select Generic if your provider is not listed. Refer to Imported Clusters for more information.	All
   Proxy (Optional)	The address of an HTTP proxy server that the Palette agent uses for outbound traffic to reach Palette.	Generic
   No Proxy (Optional)	A comma-separated list of hosts, IP addresses, or Classless Inter-Domain Routing (CIDR) ranges that bypass the proxy specified in the Proxy field.	Generic
   Host Path (Optional)	The file path on the host machine to a custom Certificate Authority (CA) certificate. Use this if the Palette agent must trust a CA that is not in the default trust store, such as when connecting to a self-hosted Palette instance that uses an internal CA or when traffic passes through a Transport Layer Security (TLS)-intercepting proxy.	All
   Container Mount Path (Optional)	The path inside the Palette agent container where the CA certificate specified in the Host Path field is mounted.	All

5. Select Full Permission mode, then Create & Open Cluster Instance to start the import.

6. You are redirected to the imported cluster's Overview tab. A set of instructions with commands is displayed on the drawer. You must issue the following commands to complete the import process.

   

7. Select Download manifest.

   info

   Once you select Download manifest, the cluster status transitions to Importing. If you close the drawer and later discover the download was blocked or did not complete, the drawer will not reopen. In this case, you must fetch the manifest using the Palette API endpoint /v1/spectroclusters/<uid>/import/manifest.

   Retrieve Manifest Manually

   Replace the placeholders in the following commands with the appropriate values.

   Parameter	Description
   <palette-endpoint>	The endpoint of your Palette instance.
   <cluster-uid>	The unique ID assigned to imported cluster. Found at Clusters > [Cluster] > Cluster ID.
   <api-key>	Your Palette API Key.
   <project-uid>	(Project scope only) The Palette project you are importing your cluster to. Found in the top-right on the Project Overview. This field is not applicable in the Tenant Admin scope.
   <jwt-token>	Your Palette Authorization Token.

   API Key

   Omit the line --header "ProjectUid: <project-uid>" \ if you are importing the cluster in the Tenant Admin scope.

   curl --silent --show-error --request GET \
      "https://<palette-endpoint>/v1/spectroclusters/<cluster-uid>/import/manifest" \
      --header "ApiKey: <api-key>" \
      --header "ProjectUid: <project-uid>" \
      --output "cluster-<cluster-uid>-manifest.yaml"

   JWT Token

   curl --silent --show-error --request GET \
      "https://<palette-endpoint>/v1/spectroclusters/<cluster-uid>/import/manifest" \
      --header "Authorization: <jwt-token>" \
      --output "cluster-<cluster-uid>-manifest.yaml"

8. Apply the manifest to your Kubernetes cluster to install the Palette agent using the appropriate download path.

   kubectl apply --filename <path-to-download>/manifest.yaml
   Example output

   namespace/cluster-69e66411d312edbed1f9c00d created
   serviceaccount/cluster-management-agent created
   clusterrole.rbac.authorization.k8s.io/read-only-mode created
   clusterrolebinding.rbac.authorization.k8s.io/read-only-mode created
   configmap/log-parser-config created
   configmap/upgrade-info-5tgb8c4chb created
   configmap/version-info-5hkbtbgh44 created
   priorityclass.scheduling.k8s.io/spectro-cluster-critical created
   deployment.apps/cluster-management-agent-lite created
   configmap/cluster-info created
   configmap/hubble-info created
   secret/hubble-secrets created
   info

   The Palette agent requires a metrics server that implements the Kubernetes Metrics API (metrics.k8s.io) to display resource utilization data such as CPU and memory usage. In full permission mode, the agent automatically detects whether a metrics server is present and installs one if none is found. If your cluster already has a metrics server, the agent uses the existing one.

9. When the Palette agent completes initializing, the drawer disappears, and your Cluster Status transitions to Running. Within a few minutes, your cluster's Health status changes to Healthy.

You now have imported a cluster into Palette with full permissions.

Validate

1. Log in to Palette.

2. From the left main menu, select Clusters.

3. From the Clusters table, select your imported cluster.

4. On the cluster Overview tab, verify your cluster has a Cluster Status of Running and a Health status of Healthy.

5. It may take several minutes for Palette to populate metrics data. Metrics data appears in the following locations:

   • Overview tab - Metrics Real-Time section

   • Usage & Costs tab

   • Workloads tab

     

Read-Only Mode

Read-only mode imports your cluster with limited RBAC permissions. The Palette agent observes the cluster and reports health, event logs, cost, and workload data, but does not modify workloads or infrastructure. You can migrate to full permission mode at any time.

Prerequisites

• Your imported cluster must meet the following requirements:

  • Use Kubernetes version 1.19.x or later.
  • Have network access to Palette SaaS or your self-hosted Palette instance.

• Your local workstation must have kubectl installed and configured to access your imported cluster.

info

Network proxy configuration is not supported in read-only mode. If your cluster requires a network proxy to communicate with Palette, use full permission mode. Refer to Imported Clusters to learn more about each mode.

Import a Cluster

1. Log in to Palette.

2. From the left main menu, select Clusters.

3. Choose Import Cluster.

4. On the Import Cluster page, complete the following information as applicable. The fields vary depending on the Cloud Type selected.

   Field	Description	Cloud Type
   Cluster Name	A unique display name for the cluster you want to import.	All
   Cloud Type	The infrastructure environment your cluster resides in. The cloud type determines what infrastructure metadata Palette displays. Supported options include AWS IaaS, Azure IaaS, GCP IaaS, and Generic. Select Generic if your provider is not listed. Refer to Imported Clusters for more information.	All
   Proxy (Optional)	The address of an HTTP proxy server that the Palette agent uses for outbound traffic to reach Palette.	Generic
   No Proxy (Optional)	A comma-separated list of hosts, IP addresses, or Classless Inter-Domain Routing (CIDR) ranges that bypass the proxy specified in the Proxy field.	Generic
   Host Path (Optional)	The file path on the host machine to a custom Certificate Authority (CA) certificate. Use this if the Palette agent must trust a CA that is not in the default trust store, such as when connecting to a self-hosted Palette instance that uses an internal CA or when traffic passes through a TLS-intercepting proxy.	All
   Container Mount Path (Optional)	The path inside the Palette agent container where the CA certificate specified in the Host Path field is mounted.	All

5. Select Read-only mode, then Create & Open Cluster Instance to start the import.

6. You are redirected to the imported cluster's Overview tab. A set of instructions with commands is displayed on the drawer. You must issue the following commands to complete the import process.

   

7. (Optional) Palette uses a metrics server that implements the Kubernetes Metrics API (metrics.k8s.io) to display resource utilization data such as CPU and memory usage. In read-only mode, the Palette agent does not have permission to install a metrics server automatically. If your cluster does not already have a metrics server, you can install one manually. Any implementation that serves the Kubernetes Metrics API is compatible.

   warning

   Without a metrics server, Palette cannot display cluster resource metrics. Other functionality such as event logs, health checks, and cost data is not affected.

   To verify if your cluster has the Kubernetes Metrics API installed, run the following command.

   kubectl get apiservices | grep metrics
   Example output

    v1beta1.metrics.k8s.io              kube-system/metrics-server   True        33m

   To verify the Kubernetes Metrics API is responding, run the following command.

   kubectl top nodes
   Example output

   NAME                                   CPU(cores)   CPU(%)   MEMORY(bytes)   MEMORY(%)
   import-cluster-palette-control-plane   212m         2%       1607Mi          20%

   If your cluster does not have a metrics server installed, use the (Optional) Install the metrics server commands displayed in the drawer to install the Kubernetes Metrics Server Helm chart.

   warning

   Add the line --set args='{--kubelet-insecure-tls}' to the command if your cluster uses self-signed Kubelet certificates, which is common for self-managed clusters.

   helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
   helm upgrade --install metrics-server metrics-server/metrics-server \
      --namespace kube-system \
      --set args='{--kubelet-insecure-tls}'

   If you do not use the --kubelet-insecure-tls argument and you have self-signed Kubelet certificates, the metrics API server will not respond. This is indicated with the output False (MissingEndpoints) when running the command kubectl get apiservices | grep metrics.

   Example of a non-responsive metrics server

   v1beta1.metrics.k8s.io    kube-system/metrics-server   False (MissingEndpoints)   7m26s

8. Select Download manifest.

   info

   Once you select Download manifest, the cluster status transitions to Importing. If you close the drawer and later discover the download was blocked or did not complete, the drawer will not reopen. In this case, you must fetch the manifest using the Palette API endpoint /v1/spectroclusters/<uid>/import/manifest.

   Retrieve Manifest Manually

   Replace the placeholders in the following commands with the appropriate values.

   Parameter	Description
   <palette-endpoint>	The endpoint of your Palette instance.
   <cluster-uid>	The unique ID assigned to imported cluster. Found at Clusters > [Cluster] > Cluster ID.
   <api-key>	Your Palette API Key.
   <project-uid>	(Project scope only) The Palette project you are importing your cluster to. Found in the top-right on the Project Overview. This field is not applicable in the Tenant Admin scope.
   <jwt-token>	Your Palette Authorization Token.

   API Key

   Omit the line --header "ProjectUid: <project-uid>" \ if you are importing the cluster in the Tenant Admin scope.

   curl --silent --show-error --request GET \
      "https://<palette-endpoint>/v1/spectroclusters/<cluster-uid>/import/manifest" \
      --header "ApiKey: <api-key>" \
      --header "ProjectUid: <project-uid>" \
      --output "cluster-<cluster-uid>-manifest.yaml"

   JWT Token

   curl --silent --show-error --request GET \
      "https://<palette-endpoint>/v1/spectroclusters/<cluster-uid>/import/manifest" \
      --header "Authorization: <jwt-token>" \
      --output "cluster-<cluster-uid>-manifest.yaml"

9. Apply the manifest to your Kubernetes cluster to install the Palette agent using the appropriate download path.

   kubectl apply --filename <path-to-download>/manifest.yaml
   Example output

   namespace/cluster-69e680a5d312edd1d203acee created
   customresourcedefinition.apiextensions.k8s.io/awscloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/azurecloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/cloudstackcloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/clusterprofiles.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/customcloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/edgecloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/edgenativecloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/gcpcloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/maascloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/nestedcloudconfigs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/packs.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/spectroclusters.cluster.spectrocloud.com created
   customresourcedefinition.apiextensions.k8s.io/vspherecloudconfigs.cluster.spectrocloud.com created
   serviceaccount/palette-manager created
   clusterrolebinding.rbac.authorization.k8s.io/palette-lite-cluster-admin-binding created
   configmap/palette-version-info-g7bkcc8gf2 created
   priorityclass.scheduling.k8s.io/palette-spectro-cluster-critical created
   deployment.apps/palette-lite-controller-manager created
   job.batch/palette-import-presetup-job created
   serviceaccount/cluster-management-agent created
   clusterrole.rbac.authorization.k8s.io/cma-lite-cluster-least-privilege-role created
   clusterrolebinding.rbac.authorization.k8s.io/cma-lite-cluster-least-privilege-binding created
   configmap/log-parser-config created
   configmap/upgrade-info-5tgb8c4chb created
   configmap/version-info-5hkbtbgh44 created
   priorityclass.scheduling.k8s.io/spectro-cluster-critical created
   deployment.apps/cluster-management-agent-lite created
   configmap/cluster-info created
   configmap/hubble-info created
   secret/hubble-secrets created

10. When the Palette agent completes initializing, the drawer disappears, and your Cluster Status transitions to Running. Within a few minutes, your cluster's Health status changes to Healthy.

You now have imported a cluster into Palette in read-only mode. Keep in mind that a cluster imported in read-only mode has limited capabilities, indicated by the disabled tabs. You can migrate to full permissions anytime by clicking Migrate To Full Permissions. Refer to Migrate to Full Permissions for additional guidance.

Validate

1. Log in to Palette.

2. From the left main menu, select Clusters.

3. From the Clusters table, select your imported cluster.

4. On the cluster Overview tab, verify your cluster has a Cluster Status of Running and a Health status of Healthy.

5. It may take several minutes for Palette to populate metrics data. Metrics data appears in the following locations:

   • Overview tab - Metrics Real-Time section

   • Usage & Costs tab

     

Next Steps

You can now monitor your imported cluster from the Palette UI. The cluster actions you can perform through Palette, such as attaching add-on profiles, depend on the import mode selected. If you imported your cluster using read-only mode, you can increase the number of actions you can take by migrating to full permissions.