Custom Resource Instances

A CustomResourceDefinition (CRD) declares a new resource type, and a Custom Resource (CR) is a concrete instance of that type in the cluster. For example, after cert-manager is installed it registers the certificates.cert-manager.io CRD, and every Certificate object you create in Kuboard is a custom resource instance.

Kuboard automatically generates a submenu for each CRD's API group under the Custom Resources menu in the left navigation, so no dedicated page needs to be developed per CR type; instance listing, creation, editing, and deletion all reuse Kuboard's generic resource management interface.

Related Resources

• Managing CRDs themselves (viewing versions and Schema, installing, uninstalling) is covered in CRD;
• Custom resource nodes also appear in the resource map; click one to jump to its instance list, see Resource Map.

Entry Point

There are two kinds of menu items under the Custom Resources (Custom Resource) item in the left navigation:

1. CustomResourceDefinitions: the CRD list page (cluster-scoped), always displayed;
2. Dynamic submenus: grouped by the CRD's API group (apiGroup), listing the resource types under each group (plural names), for example:

Custom Resources
├── CustomResourceDefinitions     # CRD list
├── cert-manager.io
│   └── certificates              # Certificate instance list
├── monitoring.coreos.com
│   └── prometheuses              # Prometheus instance list
└── ...

There are two ways to get to an instance list:

1. Expand the Custom Resources menu and click a resource type under some group (e.g. certificates);
2. On the CustomResourceDefinitions list page, click the Custom Resource List button of a CRD row.

The submenus are generated dynamically

The instance submenus are generated by the Kuboard backend from the synced CRDs read from the cluster cache: once a CRD is installed, the menu appears after the next cache synchronization completes; once a CRD is uninstalled, the menu disappears automatically. The menus are only generated when the cluster cache is healthy (ready).

Instance List Page

The list page reuses Kuboard's generic resource list, with the following main columns:

Column	Description
Checkbox	Checking items enables Batch Delete
Cluster	The cluster the instance lives in
Namespace	Only shown when the CRD's spec.scope is Namespaced
Name	The instance name; custom resources do not have a dedicated detail page, so clicking the name does not navigate anywhere
Created Time	Shown as relative time, sortable
Actions	Per-row action buttons

The top right of the page provides three generic controls:

Control	Description
Cache Status	Shows "Cache Active" when Kuboard cluster cache is enabled for this resource type, otherwise "No Cache". When the cache is enabled the list comes from the cache (pagination supported); when not enabled, queries are forwarded directly to the Kubernetes API Server (pagination not supported)
Search / Tree Toggle	Tree mode filters on the left by Cluster → Namespace; search mode queries after selecting a cluster and namespace at the top
Refresh	Manually refresh the list; auto-refresh can also be enabled

The namespace column follows the CRD's scope

Resources whose CRD declares cluster scope (spec.scope: Cluster), such as ClusterIssuer and StorageClass-like extensions, do not show the namespace column, nor do they require selecting a namespace when creating; resources declared namespace-scoped (Namespaced) require both.

Creating an Instance (from YAML)

Create from YAML is the only way to create a custom resource instance; Kuboard does not provide a form generated from the CRD Schema.

1. Click the Create button at the top right of the list page to open the "Create {Resource Type} Object" dialog;
2. Cluster: select the target cluster (only clusters in the ready state are listed);
3. If the resource is namespace-scoped, select a Namespace;
4. Creation Method: only "Create from YAML" is offered;
5. Click OK, and Kuboard first checks that this resource is available on the cluster, then opens the YAML editor pre-filled with a template (using cert-manager's Certificate as an example):

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  namespace: default
  name: ""

6. Fill in name and spec and other fields on top of the template, then click Save to submit.

After submitting, an Operation Result dialog pops up showing the execution status of each request one by one (executing/succeeded/failed/cancelled); on failure you can click the error details to see the reason.

Field validity is validated by the API Server

Kuboard only submits the YAML to Kubernetes; it does not turn the CRD's versions[].schema (OpenAPI v3) into form inputs. Whether a required field is missing in the YAML, whether field types match, and whether enum values are valid are all validated by the API Server at write time:

• Validation passes: the object is created and a new entry appears on the list page;
• Validation fails: the request is marked failed in the Operation Result dialog, and the error details give the reason (e.g. spec.dnsNames: Required value); fix the YAML as suggested and resubmit.

This also means: before writing YAML, refer to the CRD documentation or kubectl explain <kind> to understand the field structure.

Viewing and Editing YAML

Custom resources have no detail page; viewing an instance's full content (including spec and status) and modifying fields are both done through the YAML dialog.

1. In the Actions column of the instance's row, click YAML to open the "View YAML" dialog showing the fully serialized YAML of the object;
2. If the current account has the update permission on this resource, the editor is directly editable; otherwise it is read-only;
3. After editing, click Save, and a Compare dialog pops up first showing the diff between the YAML before and after modification line by line; confirm to submit (written via apply);
4. After submitting, success or failure is likewise reported through the Operation Result dialog.

Modified version" before saving -->

System fields are preserved automatically

System fields such as status, metadata.managedFields, metadata.resourceVersion, and metadata.uid are automatically preserved or stripped by Kuboard on save, so there is no need to handle them manually; normal editing only requires paying attention to spec and your own labels and annotations.

Deleting an Instance

Deleting a Single Instance

1. In the Actions column of the instance's row, click Delete to open the "Delete K8S Object" dialog;
2. The top of the dialog lists the object's cluster, namespace, object name, and other information;
3. Fully type the instance name in Enter the object name (to prevent accidental deletion), with optional settings:
   • GracePeriod: the grace period in seconds; 0 means not set;
   • Propagation Policy: Background (default, Kubernetes deletes the object first and asynchronously reaps its dependents), Foreground (deletes dependents before the object), Orphan (does not cascade-delete dependents); when not set, the object's metadata.finalizer decides;
4. Click OK to delete; the result is reported through the Operation Result dialog, showing "Object deleted successfully" on success, and the list then refreshes automatically.

Batch Delete

1. Check multiple instance rows in the list (first-column checkboxes);
2. Click the Batch Delete button in the table header;
3. If the checked entries include objects that still exist in the cluster as well as entries that have expired from the cache, the dialog lists the two categories separately, and deletion is confirmed per category; after confirmation each entry is deleted one by one with the operation results shown.

Think through the consequences before deleting an instance

• If the CRD's spec declares finalizers, the object enters the Terminating state after deletion and does not actually disappear until the controller responsible for it completes cleanup and removes the finalizer — an instance that "cannot be deleted" from the list is usually caused by a finalizer or the controller's cleanup flow;
• If the instance has ownerReferences, deleting the owner cascades to the instance according to the owner's deletion policy;
• Deleting a CR triggers the corresponding custom controller's (Operator's) reclamation logic, such as revoking certificates, deleting downstream Secrets, and releasing underlying resources. First confirm who uses this CR and what deleting it will affect.

FAQ

Symptom	Cause and resolution
A certain type of custom resource is not visible in the menu	The CRD has not yet been synced to the cluster cache, or the cluster cache is unhealthy. Confirm the CRD is installed and the cluster is in the ready state, then wait for the next cache sync
The Create button is disabled, or clicking it reports the resource is unavailable	The current account lacks the create/list permission on this resource, or the target cluster does not provide this API (CRD not installed, or version unsupported)
Validation errors when creating/editing	The YAML does not conform to the CRD's versions[].schema; fix it according to the error details in the Operation Result dialog
The instance still shows in the list after deletion	The object is in the Terminating state (finalizer cleanup not finished), or the list is in cache mode and has not refreshed yet; click the Refresh button