Merge pull request #100 from vshn/keycloak

Add Keycloak docs

docs/modules/ROOT/nav.adoc

@@ -63,6 +63,15 @@
 ** xref:exoscale-dbaas/kafka/usage.adoc[Usage]
 ** xref:exoscale-dbaas/kafka/delete.adoc[Deletion]
 
+.Keycloak
+* xref:vshn-managed/keycloak/index.adoc[On cloudscale.ch]
+** xref:vshn-managed/keycloak/create.adoc[Creation]
+** xref:vshn-managed/keycloak/maintenance.adoc[]
+** xref:vshn-managed/keycloak/usage.adoc[Usage]
+** xref:vshn-managed/keycloak/delete.adoc[Deletion]
+** xref:vshn-managed/keycloak/plans.adoc[]
+** xref:vshn-managed/keycloak/restore.adoc[Restore]
+
 .OpenSearch
 * xref:exoscale-dbaas/opensearch/index.adoc[On Exoscale]
 ** xref:exoscale-dbaas/opensearch/create.adoc[Creation]

docs/modules/ROOT/pages/references/secrets.adoc

@@ -206,3 +206,28 @@ stringData:
 
 NOTE: Not all fields apply to all providers
 // end::kafka[]
+
+== Keycloak
+
+The example secrets on this page contains the plaintext values for the given keys.
+
+// tag::keycloak[]
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: keycloak-creds
+stringData:
+  KEYCLOAK_HOST: "example.keycloak.com" # <1>
+  KEYCLOAK_PASSWORD: "my-password" # <2>
+  KEYCLOAK_USERNAME: "admin" # <3>
+
+----
+<1> Kubernetes internal hostname
+<2> Password of admin user
+<3> Username
+
+
+NOTE: Not all fields apply to all providers
+// end::keycloak[]

docs/modules/ROOT/pages/vshn-managed/keycloak/create.adoc

@@ -0,0 +1,55 @@
+= Create a Keycloak service
+
+Apply the following object on your namespace, as specified by its YAML description.
+
+.Example to create a Keycloak instance
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: keycloak-app1-prod # <1>
+  namespace: prod-app # <2>
+spec:
+  parameters:
+    service:
+      version: "23" # <3>
+      postgreSQLParameters: {} # <4>
+    size: # <5>
+      plan: standard-2
+  writeConnectionSecretToRef:
+    name: keycloack-creds # <6>
+----
+<1> Instance name
+<2> The namespace where the object will be created
+<3> Keycloak version
+<4> PostgreSQL database parameters. See xref:vshn-managed/postgresql/index.adoc[PostgreSQL by VSHN]
+<5> Size of the Keycloak instance. See xref:vshn-managed/keycloak/plans.adoc[Plans and Sizing] for more information.
+<6> Secret where the connection details are provisioned. This secret shouldn't exist before creation.
+
+NOTE: To get more information about all available configuration options, please see the xref:references/crds.adoc#k8s-api-github-com-vshn-component-appcat-apis-vshn-v1-vshnmkeycloak[API Reference]
+
+== Inspect your new Keycloak service
+
+[source,bash]
+----
+$  oc get vshnkeycloak.vshn.appcat.vshn.io
+NAME                SYNCED   READY   CONNECTION-SECRET   AGE
+keycloak-app1-prod   True     True    keycloak-creds       3m32s
+----
+
+When you see `True` in the READY column, it means the instance is provisioned but the pods might still be starting.
+It may take some time for the instance to be available especially during the provisioning phase.
+
+== Find the connection details
+
+The connection details are stored in a secret. You can retrieve them with the following command:
+
+[source,bash]
+----
+$ oc get secrets keycloak-creds -o yaml
+----
+
+The output of the command above is a secret specification with the following structure:
+
+include::page$references/secrets.adoc[tag=keycloak]

docs/modules/ROOT/pages/vshn-managed/keycloak/delete.adoc

@@ -0,0 +1,16 @@
+= Delete a Keycloak service
+
+== Delete non protected Keycloak instance
+
+If you do not need your Keycloak service anymore, you can delete it in the same way as you would with any other object in your cluster:
+
+[source,bash]
+----
+$ oc delete vshnkeycloak.vshn.appcat.vshn.io keycloak-app1-prod
+----
+
+[IMPORTANT]
+.Non-reversible operation
+====
+If you delete the `VSHNKeycloak` object from the cluster without having xref:vshn-managed/postgresql/deletion-protection.adoc[deletion-protection] enabled, the Keycloak instance will be deleted together with all of its data and backups!
+====

docs/modules/ROOT/pages/vshn-managed/keycloak/index.adoc

@@ -0,0 +1,12 @@
+= Keycloak by VSHN
+
+This section provides documentation related to the Keycloak service managed by VSHN in the Application Catalog.
+
+Learn more about this service, including its pricing, in our https://products.docs.vshn.ch/products/appcat/keycloak.html#_pricing[product portfolio^].
+
+TIP: Get started and xref:vshn-managed/keycloak/create.adoc[create a Keycloak instance].
+
+== Links
+
+* https://keycloak.org/[Keycloak^]
+* xref:references/crds.adoc#k8s-api-github-com-vshn-appcat-v4-apis-vshn-v1-vshnkeycloak[VSHN Application Catalog API reference]

docs/modules/ROOT/pages/vshn-managed/keycloak/maintenance.adoc

@@ -0,0 +1,26 @@
+= Scheduled Maintenance
+
+By default, there will be a security maintenance on Tuesday night (Central Europe Time).
+
+NOTE: For more information about maintenance procedures, please visit https://products.docs.vshn.ch/products/appcat/keycloak.html#_recurring_maintenance[the product description].
+
+The day and time can be adjusted as described below. Times are in the CET time zone.
+
+.Redis instance with custom maintenance
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: keycloak-app1-prod
+  namespace: prod-app
+spec:
+  parameters:
+    maintenance:
+      dayOfWeek: wednesday # <1>
+      timeOfDay: '23:30:00' # <2>
+----
+<1> The day when the maintenance should take place
+<2> The time when the maintenance should be started
+
+NOTE: PostgreSQL database is also configured to have maintenance by default. See xref:vshn-managed/postgresql/maintenance.adoc[PostgreSQL Maintenance].

docs/modules/ROOT/pages/vshn-managed/keycloak/plans.adoc

@@ -0,0 +1,138 @@
+= Plans and Sizing
+
+== Plans
+
+We provide a few preconfigured plans that should make sizing your Keycloak instance easier.
+Just choose one of the provided plans.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: example
+spec:
+  parameters:
+    size:
+      plan: standard-2
+  writeConnectionSecretToRef:
+    name: keycloak-creds
+----
+
+By default, the following plans are available on every cluster:
+
+[cols="25a,15,15,15", options="header"]
+|===
+| Plan | CPU | Memory | Disk
+| standard-2 | 500m | 2Gi | 16Gi
+| standard-4 | 1 | 4Gi | 16Gi
+| standard-8 | 2 | 8Gi | 16Gi
+|===
+
+Depending on which cluster you're working with, there might be some slight differences in available plans.
+You can see all available plans running:
+
+[source,bash]
+----
+$ kubectl explain vshnkeycloak.spec.parameters.size.plan
+
+GROUP:      vshn.appcat.vshn.io
+KIND:       VSHNKeycloak
+VERSION:    v1
+
+FIELD: plan <string>
+
+DESCRIPTION:
+    Plan is the name of the resource plan that defines the compute resources.
+
+    The following plans are available:
+
+      standard-2 - CPU: 500m; Memory: 2Gi; Disk: 16Gi
+
+      standard-4 - CPU: 1; Memory: 4Gi; Disk: 16Gi
+
+      standard-8 - CPU: 2; Memory: 8Gi; Disk: 16Gi
+
+----
+
+[WARNING]
+.About APPUiO Cloud
+====
+On https://docs.appuio.cloud[APPUiO Cloud^] two important differences apply:
+
+* The `standard-8` plan is not available as it requests more memory than the https://docs.appuio.cloud/user/references/default-quota.html[Default Quota] allows.
+If you need a larger instance, please contact https://docs.appuio.cloud/user/contact.html[APPUiO Cloud support] and manually request more memory according to <<_custom_sizing>>.
+====
+
+== Custom Sizing
+
+While we provide some pre-configured plans, you are free to choose custom values for CPU, memory, and disk size.
+To do that simply set `spec.parameters.size.disk`, `spec.parameters.size.cpu`, `spec.parameters.size.memory`, `spec.parameters.size.requests.cpu` or `spec.parameters.size.requests.memory`.
+
+The following example would keep the memory requests from the `standard-2` plan while increasing the CPU request to `1` and the CPU limits to `9`.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: example
+spec:
+  parameters:
+    size:
+      plan: standard-2
+      cpu: "9"
+      requests:
+        cpu: "1"
+  writeConnectionSecretToRef:
+    name: keycloak-creds
+----
+
+NOTE: Changing the disk size from a default plan will restart the Keycloak pods. Any further disk size changes should not trigger a restart.
+
+NOTE: We don't recommend setting the requests to a lower value then the limit, as this might negatively impact the performance and stability of your instance.
+
+[WARNING]
+.APPUiO Cloud Fair Use Policy
+====
+On APPUiO Cloud, the https://docs.appuio.cloud/user/explanation/fair-use-policy.html[Fair Use Policy] also applies to all AppCat Services by VSHN.
+You will be billed extra for CPU requests that exceed the memory to CPU ratio.
+
+The default plans all adhere to the Fair Use Policy.
+====
+
+== Node Selectors
+
+You have the option to specify a custom node selector for your Keycloak instance.
+This allows you to assign the instance to a specific node, which can be helpful if your cluster has dedicated nodes to run databases on.
+
+The following configuration would create a Keycloak instance that runs on a node with the label `speed=fast`.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: example
+spec:
+  parameters:
+    size:
+      plan: standard-4
+    scheduling:
+      nodeSelector:
+        speed: fast # <1>
+  writeConnectionSecretToRef:
+    name: keycloak-creds
+----
+<1> Annotation specifying a faster node.
+
+Please consult the Kubernetes documentation on https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/[how to assign workloads to nodes using node selectors].
+
+
+[WARNING]
+.APPUiO Cloud Node Classes
+====
+On APPUiO Cloud, this can be used to schedule instances on specific https://docs.appuio.cloud/user/references/node-classes.html[Node Classes].
+
+However, this can also be done by choosing the `standard-x` or `plus-X` plans, which will schedule the instance on `flex` or `plus` nodes.
+====

docs/modules/ROOT/pages/vshn-managed/keycloak/restore.adoc

@@ -0,0 +1,4 @@
+= Restores
+
+Self-service restores aren't implemented yet. If you need to restore keycloak
+please contact our mailto:support@vshn.ch[Support].

docs/modules/ROOT/pages/vshn-managed/keycloak/usage.adoc

@@ -0,0 +1,68 @@
+= Using a Keycloak service with FQDN
+
+== Issue a Keycloak instance
+The YAML code below creates the service `VSHNKeycloak` with a Full Qualified Domain Name(FQDN).
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNKeycloak
+metadata:
+  name: keycloak-app1-prod
+  namespace: prod-app
+spec:
+  parameters:
+    service:
+      version: "23"
+      fqdn: my-keycloak.example.com # <1>
+    size:
+      plan: standard-2
+  writeConnectionSecretToRef:
+    name: keycloak-creds-connection # <2>
+----
+
+<1> Your full qualified domain name
+<2> Credentials to access the keycloak
+
+== Configure your DNS server
+
+On APPUiO Cloud we provide you with a cert-manager setup which you can use to create, sign, install and renew certificates for your domains running on APPUiO Cloud.
+
+To create a certificate for the Keycloak FQDN in your domain, you need to create a CNAME record in your domain’s DNS pointing to your APPUiO Zone’s well-defined cname record.
+
+[source, text]
+----
+my-keycloak  IN  CNAME  cname.cloudscale-lpg-0.appuio.cloud.
+----
+
+== Access Keycloak
+
+Once the Keycloak instance is running in the cluster and DNS server has been configured with the new CNAME then the service should be accessible in your browser via FQDN `my-keycloak.example.com` with credentials from `keycloak-creds-connection` secret.
+The `admin` password can be changed but be aware the secret credentials will not be valid anymore.
+
+[WARNING]
+Our keycloak service uses an internal administrator account named `internaladmin`.
+It's used by VSHN for various scripts and configurations.
+Changing the user credentials of `internaladmin` account may break your instance!
+
+== Debug the service
+
+To check the status and potential issues or errors in the service, check the `status` field of the new object:
+
+[source,bash]
+----
+$  oc describe vshnkeycloak.vshn.appcat.vshn.io my-keycloak-example
+[...]
+Status:
+  Conditions:
+    Last Transition Time:  2024-03-28T10:08:04Z
+    Reason:                ReconcileSuccess
+    Status:                True
+    Type:                  Synced
+    Last Transition Time:  2024-03-28T10:09:30Z
+    Reason:                Available
+    Status:                True
+    Type:                  Ready
+  Connection Details:
+    Last Published Time:  2024-03-28T10:09:30Z
+----

docs/modules/ROOT/pages/vshn-managed/mariadb/index.adoc

@@ -9,4 +9,4 @@ TIP: Get started and xref:vshn-managed/mariadb/create.adoc[create a MariaDB inst
 == Links
 
 * https://mariadb.org/[Mariadb^]
-* xref:references/crds.adoc#k8s-api-github-com-vshn-component-appcat-apis-vshn-v1-vshnmariadb[VSHN Application Catalog API reference]
+* xref:references/crds.adoc#k8s-api-github-com-vshn-appcat-v4-apis-vshn-v1-vshnmariadb[VSHN Application Catalog API reference]

docs/modules/ROOT/pages/vshn-managed/postgresql/index.adoc

@@ -9,4 +9,4 @@ TIP: Get started and xref:vshn-managed/postgresql/create.adoc[create a PostgreSQ
 == Links
 
 * https://www.postgresql.org/[PostgreSQL^]
-* xref:references/crds.adoc#k8s-api-github-com-vshn-component-appcat-apis-vshn-v1-vshnpostgresql[VSHN Application Catalog API reference]
+* xref:references/crds.adoc#k8s-api-github-com-vshn-appcat-v4-apis-vshn-v1-vshnpostgresql[VSHN Application Catalog API reference]

docs/modules/ROOT/pages/vshn-managed/redis/index.adoc

@@ -9,4 +9,4 @@ TIP: Get started and xref:vshn-managed/redis/create.adoc[create a Redis instance
 == Links
 
 * https://redis.io/[Redis^]
-* xref:references/crds.adoc#k8s-api-github-com-vshn-component-appcat-apis-vshn-v1-vshnredis[VSHN Application Catalog API reference]
+* xref:references/crds.adoc#k8s-api-github-com-vshn-appcat-v4-apis-vshn-v1-vshnredis[VSHN Application Catalog API reference]