docs

Author: mjudeikis

README.md

@@ -64,11 +64,25 @@ To get familiar with setting up the environment, please check out docs at [kube-
 
 ## API Changes in v0.6.0 release
 
-Addition of `PermissionClaims` to APIServiceExportSpec. It allows service provider to specify what additional resources are needed by the service consumer to effectively use the exported API. In example of a database service, the service consumer might need to create Secrets for database credentials, or ConfigMaps for configuration settings.
-
-Because objects are namespaced on provider and consumer side, to establish correct RBAC `APIServiceNamespace` controller now creates Roles and RoleBindings.
-There is caviate that if backend operates in `ClusterScope` mode, the necessary cluster-wide permissions are created. 
-Importnat: If provider wants to iniciate object, like `ConfigMap` or `Secret`, the provider needs to create `APIServiceNamespace` first, so that the necessary Roles and RoleBindings are created. This will 
+### Catalog API
+Introduction of new `Collection` and `Module` CRDs for better service organization:
+- **Collections**: Function as folders in the UI, grouping related modules
+- **Modules**: Group multiple CRDs with their related resources and permission claims
+
+### Enhanced Permission Claims
+Major improvements to `PermissionClaims` in APIServiceExportSpec:
+- **NamedResources**: Specify exact resources by name and namespace
+- **Combined Selectors**: Use both label selectors AND named resources (both must match)
+- **Granular Control**: More precise access control for service resources
+
+### Provider-side Namespace Management
+Enhanced namespace management on the provider side:
+- **APIServiceNamespace Controller**: Automatically creates Roles and RoleBindings
+- **Namespace Isolation**: Each consumer gets isolated provider-side namespaces  
+- **RBAC Automation**: Proper permissions created based on scope (namespaced vs cluster-scoped)
+- **Namespace Pre-provisioning**: Providers can pre-create namespaces for better UX
+
+**Important**: When `ClusterScope` mode is used, cluster-wide permissions are created instead of namespaced ones. 
 
 ## API Changes in v0.5.0 release
 

docs/content/.pages

@@ -2,6 +2,7 @@ nav:
   - Home:
     - index.md
   - Setup: setup
+  - Usage: usage
   - Contributing: contributing
   - Developers: developers
   - Reference: reference

docs/content/index.md

@@ -11,6 +11,13 @@ kube-bind is a prototype project that aims to provide better support for service
 - The service provider does not inject controllers/operators into the service consumer's cluster.
 - A single vendor-neutral, OpenSource agent per consumer cluster connects it with the requested services.
 
+## Key Features
+
+- **Catalog API**: Organize exported services using Collections (folders) and Modules (service definitions)
+- **Provider-side Namespace Management**: Automatic namespace provisioning and RBAC setup on provider clusters
+- **Enhanced Permission Claims**: Granular resource access with both label selectors and named resource support
+- **Multi-backend Support**: Works with standard Kubernetes and KCP backends through multicluster-runtime
+
 ## Quickstart
 
 To get started with trying out kube-bind on your local system, check out our [Quickstart](./setup/quickstart.md) instructions.

docs/content/setup/index.md

@@ -29,4 +29,12 @@ Choose the setup that best fits your use case:
 - Use **Helm Deployment** for production environments with standard Kubernetes
 - Use **KCP Integration** for advanced multi-tenant scenarios with workspace isolation
 
+## Next Steps
+
+After completing your setup, explore these guides:
+
+- **[Usage Guide](../usage/index.md)**: Learn common workflows and the new Catalog API
+- **[Migration Guide](../usage/migration.md)**: Upgrade from previous versions
+- **[Developer Documentation](../developers/index.md)**: Understand the architecture and contribute
+
 {% include "partials/section-overview.html" %}

docs/content/setup/quickstart.md

@@ -75,6 +75,47 @@ kubectl ws create provider --enter
    kubectl apply -f deploy/examples/crd-foo.yaml
    ```
 
+* Optionally, create Catalog API resources for better organization (v0.6.0+):
+
+   ```shell
+   # Create a Module for better service definition
+   kubectl apply -f - <<EOF
+   apiVersion: catalog.kube-bind.io/v1alpha1
+   kind: Module
+   metadata:
+     name: mongodb-module
+   spec:
+     scope: Namespaced
+     resources:
+       - group: mangodb.com
+         version: v1alpha1  
+         resource: mangodbs
+     permissionClaims:
+       - groupResource:
+           group: ""
+           resource: "secrets"
+         selector:
+           labelSelector:
+             matchLabels:
+               app: "mongodb"
+           namedResources:
+             - name: "mongodb-credentials"
+               namespace: "default"
+   EOF
+
+   # Create a Collection to group services
+   kubectl apply -f - <<EOF
+   apiVersion: catalog.kube-bind.io/v1alpha1
+   kind: Collection
+   metadata:
+     name: database-services
+   spec:
+     description: "Database services from our platform"
+     modules:
+       - name: mongodb-module
+   EOF
+   ```
+
 * start the backend binary with the right flags:
    ```shell
    make build

docs/content/usage/.pages

@@ -0,0 +1,4 @@
+title: Usage
+nav:
+  - index.md
+  - migration.md