Setting Up the Klutch Control Plane Cluster

To establish Klutch's multi-cluster architecture, it's essential to set up the Control Plane Cluster, which serves as the central hub for managing data services.

This guide provides platform operators with step-by-step instructions to deploy and configure the Klutch Control Plane Cluster.

Prerequisites

Before setting up the Klutch Control Plane, ensure that the required infrastructure, tools, and dependencies are in place:

Kubernetes Cluster: A running Kubernetes cluster is required to deploy the Control Plane components.
- Node Requirements: If you plan to host highly available, container-based data services using the a8s framework within the Control Plane Cluster, ensure the cluster consists of at least three nodes. Each node should have specifications equivalent to or exceeding an AWS t3a.xlarge instance (4 vCPUs and 16 GiB memory).
Helm: Version 3.2.0 or later is required for package management.
kubectl: The Kubernetes command-line tool must be installed and properly configured to interact with your cluster, and include Kustomize support (built-in from v1.14+)
Crossplane®: Klutch supports Crossplane® Version 1.17. through 1.20. (v2.x is not yet supported).
- Additionally, ensure the Server-Side Apply (SSA) flag is enabled for claims by setting:
```
--set args='{"--enable-ssa-claims"}'
```

Deploying the Control Plane

1. Install Klutch Components

Deploy the required Kubernetes objects for Klutch components to the Control Plane Cluster:

kubectl apply --kustomize https://github.com/anynines/klutchio

This command installs the necessary CustomResourceDefinitions (CRDs), composition functions and Crossplane® Providers required for Klutch's operation, including:

provider-anynines: Enables the provisioning and management of VM-based anynines data services in a Kubernetes-native way.
provider-kubernetes: Enables the provisioning and management of container-based data services using the anynines a8s-framework.

Wait for the configuration package to become healthy:

kubectl get configuration -w

2. Configure Crossplane® Providers

To fully enable Klutch, at least one of the following providers must be configured:

provider-kubernetes (for container-based a8s data services)
provider-anynines (for VM-based a9s data services)
Both, if managing both types of services

2.1 Configure provider-kubernetes (In-Cluster Provider Configuration)

The following command sets up a ProviderConfig resource for provider-kubernetes in Crossplane®. This configuration defines how Crossplane® interacts with resources within the cluster:

kubectl apply -f https://raw.githubusercontent.com/anynines/klutchio/refs/heads/main/crossplane-api/deploy/config-in-cluster.yaml

This configuration uses InjectedIdentity as the credentials source, allowing Crossplane to authenticate and manage in-cluster resources without requiring external credentials.

Check if the provider configuration has been successfully applied:

kubectl get providerconfigs.kubernetes.crossplane.io

2.2 Configure provider-anynines for VM-Based a9s Data Services

If you plan to deploy VM-based data services using provider-anynines, you must configure access to the a9s Data Services automation backend.

Obtain the credentials for a9s PostgreSQL, MariaDB, or other data services from anynines, then encode them in base64 format:

echo -n 'username' | base64

Replace <data-service> in the YAML file with the corresponding value from the table below. Additionally, replace all other placeholder values enclosed in <> with the corresponding actual values, following the specifications for each Data Service you want to deploy:

Data Service	Data-service Value
a9s KeyValue	keyvalue
a9s Logme2	logme2
a9s MariaDB	mariadb
a9s Messaging	messaging
a9s MongoDB	mongodb
a9s PostgreSQL	postgresql
a9s Prometheus	prometheus
a9s Search	search

The following YAML configuration sets up credentials and provider settings for the selected a9s Data Service. Ensure base64-encoded values are used where required.

Click to reveal the YAML configuration template for a9s Data Services

apiVersion: v1
kind: Secret
metadata:
name: <data-service>-service-broker-creds
namespace: crossplane-system
type: Opaque
data:
username: <service-broker-username-base64-encoded>
password: <service-broker-password-base64-encoded>
---
apiVersion: dataservices.anynines.com/v1
kind: ProviderConfig
metadata:
name: <data-service>-service-broker
spec:
url: <service-broker-url> # e.g. http://example.com:3000 or https://example.com:3001
# Whether the service is a Service Broker or a Backup Manager.
serviceType: servicebroker
# Optional custom TLS settings.
tls:
  # The name in the Service Broker's certificate. Required if it differs from the Service Broker hostname.
  overrideServerName: <cert-host-name> # e.g. example.com
  # Set to true to disable certificate chain and hostname validation (insecure).
  insecureSkipVerify: false
  # Secret containing a custom CA bundle (PEM). Omit if using a trusted CA.
  caBundleSecretRef:
    key: cert
    name: <data-service>-service-broker-creds
    namespace: crossplane-system
healthCheckEndpoint: "/osb_ext/v1/healthy"
providerCredentials:
  source: Secret
  username:
    secretRef:
      namespace: crossplane-system
      name: <data-service>-service-broker-creds
      key: username
  password:
    secretRef:
      namespace: crossplane-system
      name: <data-service>-service-broker-creds
      key: password
---
apiVersion: v1
kind: Secret
metadata:
name: <data-service>-backup-manager-creds
namespace: crossplane-system
type: Opaque
data:
username: <backup-manager-username-base64-encoded>
password: <backup-manager-password-base64-encoded>
---
apiVersion: dataservices.anynines.com/v1
kind: ProviderConfig
metadata:
name: <data-service>-backup-manager
spec:
url: <backup-manager-url> # e.g. http://example.com:3000 or https://example.com:3001
# Whether the service is a service broker or a backup manager.
serviceType: backupmanager
# Optional custom TLS settings.
tls:
  # The name in the Backup Manager's certificate. Required if it differs from the Backup Manager hostname.
  overrideServerName: <cert-host-name> # e.g. example.com
  # Set to true to disable certificate chain and hostname validation (insecure).
  insecureSkipVerify: false
  # Secret containing a custom CA bundle (PEM). Omit if using a trusted CA.
  caBundleSecretRef:
    key: cert
    name: <data-service>-backup-manager-creds
    namespace: crossplane-system
healthCheckEndpoint: "/v2/healthy" # Use "/instances" for a9s Backup Managers below v68
providerCredentials:
  source: Secret
  username:
    secretRef:
      namespace: crossplane-system
      name: <data-service>-backup-manager-creds
      key: username
  password:
    secretRef:
      namespace: crossplane-system
      name: <data-service>-backup-manager-creds
      key: password

note

The healthCheckEndpoint fields in the above ProviderConfigs default to /instances when not set. This endpoint is common to both service brokers and backup managers. For improved performance and scalability, dedicated health check endpoints are available and recommended. The appropriate endpoint depends on whether the ProviderConfig is for a service broker or backup manager. See the following table for information on which one to use.

Provider type	Recommended endpoint	Default endpoint
service broker	`/osb_ext/v1/healthy`	`/instances`
backup manager	`/v2/healthy` in versions v68 and above	`/instances`

Repeat this process for each additional a9s Data Service you want to enable.

Once applied, check the provider configurations:

kubectl get providerconfigs.kubernetes.crossplane.io

Next Steps

Set up the Binding Mechanism to enable klutch's services in your app clusters.

Prerequisites​

Deploying the Control Plane​

1. Install Klutch Components​

2. Configure Crossplane® Providers​

2.1 Configure provider-kubernetes (In-Cluster Provider Configuration)​

2.2 Configure provider-anynines for VM-Based a9s Data Services​

Next Steps​