Add Readme, more consistent CRD keys

README.md

@@ -1,3 +1,86 @@
 # keycloak-attribute-sync-controller
 
 Kubernetes Operator to sync Keycloak attributes to Openshift user objects.
+
+## Installation
+
+The controller can be installed using `kubectl`.
+
+```shell
+kubectl apply -k config/default
+```
+
+## Usage
+
+User Attributes stored within Keycloak can be synchronized into OpenShift. The following table describes the set of configuration options for the sync:
+
+| Name                | Description                                                                             | Defaults | Required |
+| ------------------- | --------------------------------------------------------------------------------------- | -------- | -------- |
+| `caSecret`          | Reference to a secret containing a SSL certificate to use for communication (See below) |          | No       |
+| `credentialsSecret` | Reference to a secret containing authentication details (See below)                     |          | Yes      |
+| `insecure`          | Ignore SSL verification                                                                 | `false`  | No       |
+| `loginRealm`        | Realm to authenticate against                                                           | `master` | No       |
+| `realm`             | Realm to synchronize                                                                    |          | Yes      |
+| `attribute`         | The attribute to sync to the user object                                                |          | Yes      |
+| `targetAnnotation`  | The annotation to sync the attribute to                                                 |          | No       |
+| `targetLabel`       | The label to sync the attribute to                                                      |          | No       |
+
+The following is an example of a minimal configuration that can be applied to integrate with a Keycloak provider:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: keycloack-read-users-secrets
+type: Opaque
+data:
+  username: ...
+  password: ...
+---
+apiVersion: keycloak.appuio.ch/v1alpha1
+kind: AttributeSync
+metadata:
+  name: sync-default-org
+spec:
+  url: https://id.dev.appuio.cloud/
+  realm: appuio-public
+  loginRealm: appuio-public
+  credentialsSecret:
+    name: keycloack-read-users-secrets
+    namespace: ...
+  attribute: appuio.io/default-organization
+  targetAnnotation: default-organization-syncer.appuio.io/sync-time
+```
+
+### Authenticating to Keycloak
+
+A user with rights to query for Keycloak groups must be available. The following permissions must be associated to the user:
+
+* Password must be set (Temporary option unselected) on the _Credentials_ tab
+* On the _Role Mappings_ tab, select _master-realm_ or _realm-management_ next to the _Client Roles_ dropdown and then select **query-users** and **view-users**.
+
+A secret must be created in the same namespace that contains the `GroupSync` resource. It must contain the following keys for the user previously created:
+
+* `username` - Username for authenticating with Keycloak
+* `password` - Password for authenticating with Keycloak
+
+The secret can be created by executing the following command:
+
+```shell
+oc create secret generic keycloak-attribute-sync --from-literal=username=<username> --from-literal=password=<password>
+```
+
+### Scheduled Execution
+
+A cron style expression can be specified for which a synchronization event will occur. The following specifies that a synchronization should occur nightly at 3AM
+
+```shell
+apiVersion: keycloak.appuio.ch/v1alpha1
+kind: AttributeSync
+metadata:
+  name: sync-default-org
+spec:
+  schedule: "0 3 * * *"
+```
+
+If a schedule is not provided, synchronization will occur only when the object is reconciled by the platform.

api/v1alpha1/attributesync_types.go

@@ -55,11 +55,11 @@ type AttributeSyncSpec struct {
 
 	// TargetLabel specifies the label to sync the attribute to
 	// +kubebuilder:validation:Optional
-	TargetLabel string `json:"target_label,omitempty"`
+	TargetLabel string `json:"targetLabel,omitempty"`
 
 	// TargetAnnotation specifies the label to sync the attribute to
 	// +kubebuilder:validation:Optional
-	TargetAnnotation string `json:"target_annotation,omitempty"`
+	TargetAnnotation string `json:"targetAnnotation,omitempty"`
 
 	// Schedule represents a cron based configuration for synchronization
 	// +kubebuilder:validation:Optional

config/crd/bases/keycloak.appuio.ch_attributesyncs.yaml

@@ -91,11 +91,11 @@ spec:
               schedule:
                 description: Schedule represents a cron based configuration for synchronization
                 type: string
-              target_annotation:
+              targetAnnotation:
                 description: TargetAnnotation specifies the label to sync the attribute
                   to
                 type: string
-              target_label:
+              targetLabel:
                 description: TargetLabel specifies the label to sync the attribute
                   to
                 type: string