Merge pull request #33 from anynines/add-supporting-documents

Add docs to enable integration of new services

docs/platform-operator/adding-custom-service.md

@@ -0,0 +1,67 @@
+---
+id: add-custom-service
+title: Adding a Custom Service
+---
+
+# Adding a Custom Service
+
+You can also add your own services to Klutch. This can be useful in case you want to add an internal
+service and distribute it the same way as the officially supported services. 
+
+Services are offered in the form of Kubernetes Custom Resources. We recommend that you use
+crossplane XRDs to define your service's interface for end users. This allows you to add services
+already supported by crossplane, like public clouds, Kubernetes Operators, using
+Provider-Kubernetes, or custom services by writing a crossplane provider wrapping an arbitrary API.
+You can find a examples of this at `crossplane-api/api/{common,a8s}`. We recommend that you use
+namespace scoped custom resources, to ensure that tenants can be properly isolated.
+
+Once you have set up your custom API on the control plane cluster, you need to make it available for
+binding for your users. In order to do that you can create an `APIServiceExportTemplate` custom
+resource on the control plane cluster. This lets klutch-bind know that you want to share the API
+with users. To make an API available for sharing to users, you can create a resource like this:
+
+```yaml
+apiVersion: example-backend.klutch.anynines.com/v1alpha1
+kind: APIServiceExportTemplate
+metadata:
+  name: <choose a descriptive name>
+  namespace: crossplane-system
+spec:
+  APIServiceSelector:
+    group: <your api group>
+    resource: <your resource name(plural)
+    version: <your resource version>
+```
+
+Applying this custom resource to the control plane cluster will make your API available for binding
+using the web interface. In this base configuration only the resources of that type get synchronized
+to the app cluster. If your API requires additional resources to be synchronized, for example a
+secret with connection details you need to configure the synchronization for that resource. To add
+additional resource for synchronization, you can add a "permission claim" to your
+`APIServiceExportTemplate` to let klutch-bind claim the permission to sync another resource. The
+example below shows the "servicebindings" API shared via klutch-bind, with the additional permission
+claims to synchronize secrets and config maps from the control plane cluster to the app cluster.
+Syncing of claimed resources always includes all resources of that type in all bound namespaces.
+
+```yaml
+kind: APIServiceExportTemplate
+apiVersion: example-backend.klutch.anynines.com/v1alpha1
+metadata:
+  name: "servicebindings"
+  namespace: crossplane-system
+spec:
+  APIServiceSelector:
+    resource: servicebindings
+    group: anynines.com
+  permissionClaims:
+    - group: ""
+      resource: secrets
+      version: v1
+      selector:
+        owner: Provider
+    - group: ""
+      resource: configmaps
+      version: v1
+      selector:
+        owner: Provider
+```

docs/platform-operator/creating-a-custom-crossplane-package.md

@@ -0,0 +1,51 @@
+---
+id: creating-a-custom-crossplane-package
+title: Creating a Custom Crossplane Package
+---
+
+# Creating a Custom Crossplane Package
+
+There are several reasons why you might want to create a custom Crossplane Package. For example:
+
+- Customization: You want to tweak the default setup, for example to set a custom service plan.
+- White labeling: You want to rename the API shared by Klutch to reflect your own company name.
+- Adding new functionality: You want to add a new, currently unsupported service.
+
+There are two different ways to add a custom package:
+
+1. Adding a new configuration by modifying the default configuration
+2. Adding a completely new API
+
+## Modifying the existing Configuration
+
+If you want to make small changes to the default configuration, you can check out the
+[crossplane-api developer
+guide](https://github.com/anynines/klutchio/blob/main/crossplane-api/README.md). For
+white-labeling you should follow the section on adding a new API, and remove the default
+configuration.
+
+Once you have made the modifications you want, you can push the configuration package to a OCI image
+registry of your choice, and deploy your changes to the control plane cluster by running:
+
+```sh
+# Get the name of the configuration
+$ kubectl get configurations.pkg.crossplane.io
+NAME                             INSTALLED   HEALTHY   PACKAGE                                                AGE
+w5n9a2g2-anynines-dataservices   True        True      public.ecr.aws/w5n9a2g2/anynines/dataservices:v1.3.0   73d
+
+# edit the configuration
+$ kubectl edit configurations.pkg.crossplane.io w5n9a2g2-anynines-dataservices
+
+```
+
+and then edit `spec.package` to the configuration package you have pushed to your image registry.
+
+## Adding a new API
+
+To add a new API, you need to create a crossplane package with the API you want to add. As a
+starting point you can look into the crossplane documentation for Composite Resource Definitions,
+Compositions, and Package at (https://docs.crossplane.io/latest/concepts/).
+
+Once you have created your custom API and installed it on the Provider cluster, you can add it to
+Klutch by following the [steps for adding a custom api to klutch-bind](./adding-custom-service.md)
+to make it accessible to your users.