/docs: rename CachedResource to ClusterCachedResource

neolit123 · neolit123 · commit 6792b62a3b23 · 2026-07-19T13:05:06.000+02:00
Signed-off-by: Lubomir I. Ivanov &lt;neolit123@gmail.com&gt;
diff --git a/docs/content/concepts/apis/cached-resources.md b/docs/content/concepts/apis/cached-resources.md
@@ -1,15 +1,15 @@
-# CachedResource API
+# ClusterCachedResource API
 
 !!! warning
     As of 0.29, this feature is of alpha-version quality. To use it, enable the `CachedAPIs` feature gate.
 
-A CachedResource object triggers replication of a user-defined resource from its workspace into kcp's [cache server](../sharding/cache-server.md), extending its [built-in resource set](../sharding/cache-server.md#built-in-resources) with custom types. This makes those resources available across shards, enabling implementors to build globally-aware kcp-native components. API providers can additionally expose replicated resources as read-only to consumer workspaces — see [Exporting CachedResources](#exporting-cachedresources).
+A ClusterCachedResource object triggers replication of a user-defined resource from its workspace into kcp's [cache server](../sharding/cache-server.md), extending its [built-in resource set](../sharding/cache-server.md#built-in-resources) with custom types. This makes those resources available across shards, enabling implementors to build globally-aware kcp-native components. API providers can additionally expose replicated resources as read-only to consumer workspaces — see [Exporting ClusterCachedResources](#exporting-clustercachedresources).
 
 ## Resource replication
 
 ```yaml
 apiVersion: cache.kcp.io/v1alpha1
-kind: CachedResource
+kind: ClusterCachedResource
 metadata:
   name: cpuflavors-v1
 spec:
@@ -20,16 +20,16 @@ spec:
 
 The snippet above shows an example where all `cpuflavors.v1.cloud.example.com` objects in the workspace are replicated to the cache. There are some constraints on what resources may be replicated:
 
-- There may be only one CachedResource for a particular group-version-resource triplet in the workspace.
+- There may be only one ClusterCachedResource for a particular group-version-resource triplet in the workspace.
 - The resource must be cluster scoped.
 - The resource must not be a [built-in API](./built-in.md) or kcp system API belonging to `apis.kcp.io` group.
 - The resource may be originating from a CRD or an APIBinding.
 
-Once created, resource replication progress may be checked in CachedResource's status:
+Once created, resource replication progress may be checked in ClusterCachedResource's status:
 
 ```yaml
 apiVersion: cache.kcp.io/v1alpha1
-kind: CachedResource
+kind: ClusterCachedResource
 metadata:
   name: cpuflavors-v1
 status:
@@ -50,10 +50,10 @@ status:
     local: 8 # (2)
 ```
 
-1. `cache` resource count refers to the count of objects currently in cache for this CachedResource.
-2. `local` resource count refers to the count of objects the CachedResource currently sees in its workspace.
+1. `cache` resource count refers to the count of objects currently in cache for this ClusterCachedResource.
+2. `local` resource count refers to the count of objects the ClusterCachedResource currently sees in its workspace.
 
-The objects a CachedResource is watching are always replicated in the direction **from** CachedResource's workspace **into** cache. Note that this means the only way to modify the in-cache copies is to modify the original objects. In-cache objects can be then projected into a workspace as a read-only API. This is done by creating a respective APIExport with [CachedResource virtual resource](#exporting-cachedresources), and binding to it.
+The objects a ClusterCachedResource is watching are always replicated in the direction **from** ClusterCachedResource's workspace **into** cache. Note that this means the only way to modify the in-cache copies is to modify the original objects. In-cache objects can be then projected into a workspace as a read-only API. This is done by creating a respective APIExport with [ClusterCachedResource virtual resource](#exporting-clustercachedresources), and binding to it.
 
 ```mermaid
 flowchart TD
@@ -63,31 +63,31 @@ flowchart TD
         cpuflavorsCRD["CPUFlavors CRD"]
         cpuflavorCRs["CPUFlavor objects..."]
 
-        cpuflavorsCachedResource["CPUFlavors CachedResource"]
+        cpuflavorsClusterCachedResource["CPUFlavors ClusterCachedResource"]
 
         cpuflavorCRs -."From".-> cpuflavorsCRD
-        cpuflavorsCachedResource -.Watches.-> cpuflavorCRs
+        cpuflavorsClusterCachedResource -.Watches.-> cpuflavorCRs
     end
 
-    cpuflavorsCachedResource -."Replicates CPUFlavor objects into".-> cacheServer
+    cpuflavorsClusterCachedResource -."Replicates CPUFlavor objects into".-> cacheServer
 ```
 
-You can optionally configure the following additional aspects of a CachedResource:
+You can optionally configure the following additional aspects of a ClusterCachedResource:
 
 - its identity
 - resource selector
 
 We'll talk about each of these next.
 
-### CachedResource identity
+### ClusterCachedResource identity
 
-Similar to the [APIExport identity](./exporting-apis.md#apiexport-identity) concept, there may be many CachedResources with the same group-version-resource triplet across the kcp installation. To differentiate between them and identify owners, a CachedResource object uses a unique identity key stored in a secret.
+Similar to the [APIExport identity](./exporting-apis.md#apiexport-identity) concept, there may be many ClusterCachedResources with the same group-version-resource triplet across the kcp installation. To differentiate between them and identify owners, a ClusterCachedResource object uses a unique identity key stored in a secret.
 
 The identity **key** is considered a private key and should not be shared.
 
-**Hash** calculated from that key, found at `.status.identityHash`, is considered a public key. APIExport's virtual resource definition expects this identity hash to be supplied when exporting a CachedResource.
+**Hash** calculated from that key, found at `.status.identityHash`, is considered a public key. APIExport's virtual resource definition expects this identity hash to be supplied when exporting a ClusterCachedResource.
 
-By default, creating a CachedResource object triggers creation of an identity secret with a randomly generated key in its `key` data item. You can provide your own key by referencing your secret in the object's spec:
+By default, creating a ClusterCachedResource object triggers creation of an identity secret with a randomly generated key in its `key` data item. You can provide your own key by referencing your secret in the object's spec:
 
 ```yaml
 apiVersion: v1
@@ -99,7 +99,7 @@ stringData:
   key: "<Your identity key>"
 ---
 apiVersion: cache.kcp.io/v1alpha1
-kind: CachedResource
+kind: ClusterCachedResource
 metadata:
   name: cpuflavors-v1
 spec:
@@ -112,11 +112,11 @@ spec:
 
 ### Selectors
 
-CachedResource spec has an optional [`labelSelector`](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) field which can be used to shape the set of objects it picks up.
+ClusterCachedResource spec has an optional [`labelSelector`](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) field which can be used to shape the set of objects it picks up.
 
 ```yaml
 apiVersion: cache.kcp.io/v1alpha1
-kind: CachedResource
+kind: ClusterCachedResource
 metadata:
   name: cpuflavors-v1
 spec:
@@ -127,58 +127,58 @@ spec:
     cloud.example.com/visibility: Public
 ```
 
-## Exporting CachedResources
+## Exporting ClusterCachedResources
 
-You can project the replicated read-only objects of a CachedResource into a workspace using the standard APIExport-APIBinding relationship. Create an APIExport and define [virtual resource](./exporting-apis.md#virtual-resources) for the associated [CachedResourceEndpointSlice](#cachedresourceendpointslice). Consumers can then bind to it.
+You can project the replicated read-only objects of a ClusterCachedResource into a workspace using the standard APIExport-APIBinding relationship. Create an APIExport and define [virtual resource](./exporting-apis.md#virtual-resources) for the associated [ClusterCachedResourceEndpointSlice](#clustercachedresourceendpointslice). Consumers can then bind to it.
 
 **Example user story:**
 
 - You, the **service provider**, run a cloud _Cloud Co._, including a compute service.
 - You offer a service of provisioning and running VM instances: users create an `Instance` object and voilà, they have a running VM!
     - But how do you design the API for configuring such a resource? How do you make your consumers know what configuration options are available, given the limited resources available in the cloud?
     - You've decided to offer different packages for CPUs, memory, storage, GPUs; these are represented as CRDs, e.g. `cpuflavors.cloud.example.com`, `memflavors.cloud.example.com`, with `cpu-small`, `cpu-medium`, `cpu-large`, `mem-medium`, `mem-large`, `mem-xlarge` respectively.
-    - You've created a CachedResource for each flavor type.
+    - You've created a ClusterCachedResource for each flavor type.
     - You offer the service through an APIExport containing the main `instances.cloud.example.com` resource, as well as all flavors. These are exported as [virtual resources](./exporting-apis.md#virtual-resources).
 - **Consumers** binding to your APIExport can list and get the available flavors from within their workspace (e.g. with `kubectl get cpuflavors`), and refer to them in their `Instance` spec. They cannot create, delete or otherwise modify the flavor objects in any way.
 
 See an example usage at [github.com/kcp-dev/kcp/tree/main/config/examples/virtualresources](https://github.com/kcp-dev/kcp/tree/main/config/examples/virtualresources).
 
-### CachedResourceEndpointSlice
+### ClusterCachedResourceEndpointSlice
 
-The CachedResourceEndpointSlice tracks the consumers of the associated APIExport, and needs to be created when you want to export a CachedResource.
+The ClusterCachedResourceEndpointSlice tracks the consumers of the associated APIExport, and needs to be created when you want to export a ClusterCachedResource.
 
 ```mermaid
 flowchart TD
     cacheServer["Cache server"]
     replicationVW["Replication VW"]
 
     subgraph provider["API Provider Workspace"]
-        cpuflavorsCachedResource["CPUFlavors CachedResource"]
-        cpuflavorsCachedResourceEndpointSlice["CPUFlavors CachedResourceEndpointSlice"]
+        cpuflavorsClusterCachedResource["CPUFlavors ClusterCachedResource"]
+        cpuflavorsClusterCachedResourceEndpointSlice["CPUFlavors ClusterCachedResourceEndpointSlice"]
 
-        cpuflavorsCachedResourceEndpointSlice --> cpuflavorsCachedResource
+        cpuflavorsClusterCachedResourceEndpointSlice --> cpuflavorsClusterCachedResource
     end
 
     replicationVW -."Reads from".-> cacheServer
-    cpuflavorsCachedResourceEndpointSlice -."Has an endpoint for".-> replicationVW
+    cpuflavorsClusterCachedResourceEndpointSlice -."Has an endpoint for".-> replicationVW
 ```
 
 ```yaml
 apiVersion: cache.kcp.io/v1alpha1
-kind: CachedResourceEndpointSlice
+kind: ClusterCachedResourceEndpointSlice
 metadata:
   name: cpuflavors-v1
 spec:
-  cachedResource:
+  clusterCachedResource:
     name: cpuflavors-v1 # (1)
   export:
     name: vm-provider # (2)
 ```
 
-1. Name (and optionally the cluster path) of the CachedResource this endpoint slice is referencing.
+1. Name (and optionally the cluster path) of the ClusterCachedResource this endpoint slice is referencing.
 2. Name (and optionally the cluster path) of the APIExport this endpoint slice is referenced by.
 
-Both the `cachedResource` and `export` references are immutable once set.
+Both the `clusterCachedResource` and `export` references are immutable once set.
 
 ```yaml
 apiVersion: apis.kcp.io/v1alpha2
@@ -194,27 +194,27 @@ spec:
       virtual:
         reference: # (2)
           apiGroup: cache.kcp.io
-          kind: CachedResourceEndpointSlice
+          kind: ClusterCachedResourceEndpointSlice
           name: cpuflavors-v1
         identityHash: cd2eb0837... # (3)
 ```
 
-1. Resource schema must match the schema used by the resource in the associated CachedResource.
-2. Reference to the CachedResourceEndpointSlice endpoint slice `cpuflavors-v1`.
-3. Identity hash of the `cpuflavors-v1` CachedResource object.
+1. Resource schema must match the schema used by the resource in the associated ClusterCachedResource.
+2. Reference to the ClusterCachedResourceEndpointSlice endpoint slice `cpuflavors-v1`.
+3. Identity hash of the `cpuflavors-v1` ClusterCachedResource object.
 
-A `virtual` storage definition needs (1) a reference to an [endpoint slice](./exporting-apis.md#endpoint-slices) object, and (2) a virtual resource identity. In the case of CachedResources, the endpoint slice is provided by CachedResourceEndpointSlice. The identity hash must match the one set in CachedResource's `.status.identityHash`.
+A `virtual` storage definition needs (1) a reference to an [endpoint slice](./exporting-apis.md#endpoint-slices) object, and (2) a virtual resource identity. In the case of ClusterCachedResources, the endpoint slice is provided by ClusterCachedResourceEndpointSlice. The identity hash must match the one set in ClusterCachedResource's `.status.identityHash`.
 
 ```mermaid
 flowchart TD
     subgraph provider["API Provider Workspace"]
         export["CPUFlavors APIExport"]
         schema["CPUFlavors APIResourceSchema"]
         crd["CPUFlavors CRD"]
-        cpuflavorsCachedResourceEndpointSlice["CPUFlavors CachedResourceEndpointSlice"]
+        cpuflavorsClusterCachedResourceEndpointSlice["CPUFlavors ClusterCachedResourceEndpointSlice"]
 
         export --> schema
-        export --> cpuflavorsCachedResourceEndpointSlice
+        export --> cpuflavorsClusterCachedResourceEndpointSlice
         schema -."Is equivalent to".-> crd
     end
 
diff --git a/docs/content/concepts/apis/exporting-apis.md b/docs/content/concepts/apis/exporting-apis.md
@@ -578,7 +578,7 @@ spec:
       virtual:
         reference: # (1)
           apiGroup: cache.kcp.io
-          kind: CachedResourceEndpointSlice
+          kind: ClusterCachedResourceEndpointSlice
           name: cpuflavors-v1
         identityHash: cd2eb0837... # (2)
 
@@ -587,6 +587,6 @@ spec:
 1. The `reference` block defines a reference to an [endpoint slice](#endpoint-slices) object.
 2. The `identityHash` refers to the identity hash owned by the virtual resource. This is different from the APIExport identity hash.
 
-kcp currently supports one such virtual resource: see [CachedResource API](./cached-resources.md) for more information.
+kcp currently supports one such virtual resource: see [ClusterCachedResource API](./cached-resources.md) for more information.
 
 Virtual resources are generic, and as long as the source virtual workspace implements the endpoint slice machinery, it can be used in APIExport's `virtual` storage definition.
diff --git a/docs/content/concepts/sharding/cache-server.md b/docs/content/concepts/sharding/cache-server.md
@@ -93,8 +93,8 @@ The set of object types replicated to the cache server is wired up by the
 | `apiexportendpointslices` | `apis.kcp.io/v1alpha1` | always |
 | `apiresourceschemas` | `apis.kcp.io/v1alpha1` | always |
 | `apiconversions` | `apis.kcp.io/v1alpha1` | always |
-| `cachedresources` | `cache.kcp.io/v1alpha1` | always |
-| `cachedresourceendpointslices` | `cache.kcp.io/v1alpha1` | always |
+| `clustercachedresources` | `cache.kcp.io/v1alpha1` | always |
+| `clustercachedresourceendpointslices` | `cache.kcp.io/v1alpha1` | always |
 | `shards` | `core.kcp.io/v1alpha1` | always |
 | `workspacetypes` | `tenancy.kcp.io/v1alpha1` | always |
 | `mutatingwebhookconfigurations` | `admissionregistration.k8s.io/v1` | always |
@@ -106,7 +106,7 @@ The set of object types replicated to the cache server is wired up by the
 | `clusterrolebindings` | `rbac.authorization.k8s.io/v1` | annotated `core.kcp.io/replicate` |
 
 User-defined types are added on top of this set via the
-[CachedResource API](../apis/cached-resources.md).
+[ClusterCachedResource API](../apis/cached-resources.md).
 
 Objects in clusters whose name starts with `system:` are excluded from
 replication.
@@ -150,12 +150,12 @@ unrelated tenant RBAC stays local.
   but does not push the binding back.
 - **`Partition` / `PartitionSet`.** These are configuration objects consumed
   in the workspace where they live and referenced by `APIExportEndpointSlice`.
-- **Identity secrets.** A `CachedResource`'s identity secret is created
+- **Identity secrets.** A `ClusterCachedResource`'s identity secret is created
   locally per shard, not replicated.
 
 ### Adding New Resources
 
-User-defined resources can be added to the cache server using the [CachedResource API](../apis/cached-resources.md). A CachedResource object triggers replication of a cluster-scoped resource from a workspace into the cache, making it available across shards alongside the built-in resource set.
+User-defined resources can be added to the cache server using the [ClusterCachedResource API](../apis/cached-resources.md). A ClusterCachedResource object triggers replication of a cluster-scoped resource from a workspace into the cache, making it available across shards alongside the built-in resource set.
 
 ### Deletion of Data
 
diff --git a/docs/content/setup/production/overview.md b/docs/content/setup/production/overview.md
@@ -19,7 +19,7 @@ The main API endpoint for clients to access kcp. This is the main entry point fo
 
   1. **Workspace scheduling**: When a new workspace is scheduled, the shard contacts the front-proxy to randomly pick a shard for the new workspace
 
-  2. **Endpoint updates**: When an `APIExportEndpointSlice` or `CachedResourceEndpointSlice` URL is updated, the update happens via the front-proxy
+  2. **Endpoint updates**: When an `APIExportEndpointSlice` or `ClusterCachedResourceEndpointSlice` URL is updated, the update happens via the front-proxy
 
 **Configuration:**
 - Set `--externalHostname` or `spec.external.hostname` in front-proxy or shard configurations
