> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Resources

> Browse and manage Custom Resource Definitions (CRDs) and their instances

Custom Resources extend Kubernetes with new resource types defined by Custom Resource Definitions (CRDs). They enable you to work with operator-managed resources like Certificates, Issuers, and other custom workloads through a unified interface.

## Key Concepts

<CardGroup cols={2}>
  <Card title="CRD" icon="puzzle">
    Custom Resource Definition - A schema that defines a new resource type in Kubernetes.
  </Card>

  <Card title="Custom Resource" icon="box">
    An instance of a CRD, similar to how a Pod is an instance of the Pod resource type.
  </Card>

  <Card title="API Group" icon="folder-tree">
    The API group that the CRD belongs to (e.g., `cert-manager.io`, `networking.istio.io`).
  </Card>

  <Card title="Scope" icon="globe">
    Whether resources are **Namespaced** (exist within a namespace) or **Cluster**-scoped (cluster-wide).
  </Card>
</CardGroup>

<Info>
  CRDs are cluster-scoped resources that define new types. Custom Resources (instances) can be either namespaced or cluster-scoped depending on the CRD definition.
</Info>

## Required Permissions

| Action                         | Permission                                     |
| ------------------------------ | ---------------------------------------------- |
| View CRDs and Custom Resources | `iam:project:infrastructure:kubernetes:read`   |
| Create Custom Resources        | `iam:project:infrastructure:kubernetes:write`  |
| Edit Custom Resources          | `iam:project:infrastructure:kubernetes:write`  |
| Delete Custom Resources        | `iam:project:infrastructure:kubernetes:delete` |

## CRD Properties

| Property        | Description                                              |
| --------------- | -------------------------------------------------------- |
| **Name**        | Full CRD name (e.g., `certificates.cert-manager.io`)     |
| **Group**       | API group (e.g., `cert-manager.io`)                      |
| **Version**     | API version (e.g., `v1`, `v1beta1`)                      |
| **Kind**        | Resource type name (e.g., `Certificate`)                 |
| **Plural**      | Plural form used in API paths (e.g., `certificates`)     |
| **Scope**       | `Namespaced` or `Cluster`                                |
| **Established** | Whether the CRD is ready for use                         |
| **Short Names** | Abbreviations for kubectl (e.g., `cert` for Certificate) |
| **Categories**  | Groups the resource belongs to (e.g., `all`)             |

## How to Browse CRDs

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Browse CRD Tree">
    The left panel shows all CRDs grouped by API group. Expand groups to see individual CRDs.
  </Step>

  <Step title="Select a CRD">
    Click on a CRD to view its custom resources in the right panel.
  </Step>

  <Step title="Select Namespace (if applicable)">
    For namespaced CRDs, select a namespace to filter resources.
  </Step>
</Steps>

## How to View Custom Resources

<Steps>
  <Step title="Select a CRD">
    Click on a CRD in the tree panel to load its resources.
  </Step>

  <Step title="View Resource List">
    The right panel displays all instances of the selected CRD type.
  </Step>

  <Step title="Click Resource Name">
    Click on a resource name to open the detail drawer with full spec and status.
  </Step>

  <Step title="Review Details">
    View resource information including:

    * **Spec**: The desired state configuration
    * **Status**: The current state reported by the controller
    * **Labels & Annotations**: Metadata
    * **Owner References**: Parent resources
    * **Finalizers**: Cleanup hooks
  </Step>
</Steps>

## How to Create a Custom Resource

<Steps>
  <Step title="Select a CRD">
    Choose the CRD type you want to create an instance of.
  </Step>

  <Step title="Click Create Button">
    Click the **Create \[Kind]** button in the header.
  </Step>

  <Step title="Write YAML">
    Enter the resource manifest. The YAML editor provides the correct apiVersion and kind.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

## How to Edit a Custom Resource

<Steps>
  <Step title="Find the Resource">
    Locate the resource in the list.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the resource row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the YAML editor.
  </Step>

  <Step title="Modify and Save">
    Edit the resource spec and click **Update** to apply changes.
  </Step>
</Steps>

## How to Delete a Custom Resource

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the resource row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. The controller managing this resource may perform cleanup operations.
  </Step>
</Steps>

<Warning>
  Deleting a custom resource may trigger cascading deletions if the resource owns other resources. Controllers may also perform cleanup operations defined by finalizers.
</Warning>

## Common CRD Examples

### cert-manager

| CRD                              | Kind          | Description                          |
| -------------------------------- | ------------- | ------------------------------------ |
| `certificates.cert-manager.io`   | Certificate   | TLS certificates                     |
| `issuers.cert-manager.io`        | Issuer        | Namespace-scoped certificate issuers |
| `clusterissuers.cert-manager.io` | ClusterIssuer | Cluster-wide certificate issuers     |

### Istio

| CRD                                    | Kind            | Description             |
| -------------------------------------- | --------------- | ----------------------- |
| `virtualservices.networking.istio.io`  | VirtualService  | Traffic routing rules   |
| `destinationrules.networking.istio.io` | DestinationRule | Traffic policies        |
| `gateways.networking.istio.io`         | Gateway         | Ingress/egress gateways |

### ArgoCD

| CRD                           | Kind           | Description                    |
| ----------------------------- | -------------- | ------------------------------ |
| `applications.argoproj.io`    | Application    | GitOps application definitions |
| `applicationsets.argoproj.io` | ApplicationSet | Application generators         |
| `appprojects.argoproj.io`     | AppProject     | Application grouping           |

### Prometheus Operator

| CRD                                         | Kind               | Description                |
| ------------------------------------------- | ------------------ | -------------------------- |
| `servicemonitors.monitoring.coreos.com`     | ServiceMonitor     | Service scraping rules     |
| `prometheusrules.monitoring.coreos.com`     | PrometheusRule     | Alerting rules             |
| `alertmanagerconfigs.monitoring.coreos.com` | AlertmanagerConfig | Alertmanager configuration |

## Example Custom Resource

### Certificate (cert-manager)

```yaml theme={null}
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-tls
  namespace: default
spec:
  secretName: example-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - example.com
    - www.example.com
```

### VirtualService (Istio)

```yaml theme={null}
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-service-route
  namespace: default
spec:
  hosts:
    - my-service
  http:
    - route:
        - destination:
            host: my-service
            port:
              number: 80
```

## Scope Types

| Scope          | Description                        | Namespace Required |
| -------------- | ---------------------------------- | ------------------ |
| **Namespaced** | Resources exist within a namespace | Yes                |
| **Cluster**    | Resources are cluster-wide         | No                 |

<Tip>
  For namespaced CRDs, select a namespace to view resources in that namespace. Cluster-scoped CRDs show all resources regardless of namespace selection.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CRD not appearing in the list">
    * Verify the CRD is installed in the cluster
    * Check if you have read permission for the CRD
    * Ensure the cluster connection is working
    * Try refreshing the page
  </Accordion>

  <Accordion title="Custom resource creation fails">
    * Verify the YAML syntax is correct
    * Check that required fields are present
    * Ensure the namespace exists (for namespaced resources)
    * Check controller logs for validation errors
    * Verify the CRD is established
  </Accordion>

  <Accordion title="Resource stuck in deleting state">
    * Check for finalizers on the resource
    * Verify the controller managing the resource is running
    * Check controller logs for cleanup errors
    * Finalizers may need manual removal in some cases
  </Accordion>

  <Accordion title="Status not updating">
    * Verify the controller (operator) is running
    * Check controller logs for errors
    * Ensure the controller has permissions to update status
    * Some resources may take time to reconcile
  </Accordion>

  <Accordion title="CRD shows 'Not Established'">
    * The CRD may have validation errors
    * Check CRD conditions for error messages
    * Verify CRD YAML is syntactically correct
    * Controller may need to be restarted
  </Accordion>

  <Accordion title="Cannot find resources for a CRD">
    * Verify you've selected the correct namespace
    * Check if resources exist using kubectl
    * Some CRDs may require specific permissions
    * Ensure the API version matches the installed CRD version
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is a Custom Resource Definition (CRD)?">
    A CRD extends the Kubernetes API by defining a new resource type. Once a CRD is installed, you can create, read, update, and delete instances of that resource type just like built-in resources (Pods, Services, etc.).
  </Accordion>

  <Accordion title="Who creates CRDs?">
    CRDs are typically installed by:

    * **Operators**: Software like cert-manager, Istio, ArgoCD
    * **Helm charts**: As part of application deployment
    * **Administrators**: For custom application needs

    You generally don't create CRDs manually - you install operators that bring their own CRDs.
  </Accordion>

  <Accordion title="What is the difference between Namespaced and Cluster scope?">
    **Namespaced** CRDs create resources that exist within a namespace, similar to Pods or Deployments. Different namespaces can have resources with the same name.

    **Cluster**-scoped CRDs create resources that are cluster-wide, similar to Nodes or ClusterRoles. Names must be unique across the entire cluster.
  </Accordion>

  <Accordion title="What does 'Established' mean?">
    An established CRD is one that has been successfully validated and is ready for use. If a CRD is not established, there may be validation errors in its definition that prevent it from being used.
  </Accordion>

  <Accordion title="How do I know which operator manages a CRD?">
    Look at the API group in the CRD name:

    * `cert-manager.io` → cert-manager
    * `networking.istio.io` → Istio
    * `argoproj.io` → ArgoCD
    * `monitoring.coreos.com` → Prometheus Operator

    The group typically indicates the project or organization that created the CRD.
  </Accordion>

  <Accordion title="Can I edit CRDs themselves?">
    This interface allows you to manage custom resources (instances), not the CRD definitions themselves. CRD modifications should be done through the operator's upgrade process or directly with kubectl.
  </Accordion>

  <Accordion title="Why is my resource not being processed?">
    Custom resources are processed by controllers (operators). If your resource isn't being processed:

    * Verify the operator is installed and running
    * Check operator logs for errors
    * Ensure the resource spec is valid
    * Check if there are dependency issues (e.g., missing referenced resources)
  </Accordion>

  <Accordion title="What are finalizers?">
    Finalizers are hooks that ensure cleanup operations complete before a resource is deleted. If a resource has finalizers, deletion is blocked until the controller removes them after completing cleanup. Stuck resources often have finalizers that couldn't be processed.
  </Accordion>
</AccordionGroup>