Basic Deployment using the Keycloak Operator

Co-authored-by: Václav Muzikář <vmuzikar@redhat.com>

docs/guides/src/main/operator/basic-deployment.adoc

@@ -0,0 +1,174 @@
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/kc.adoc" as kc>
+<#import "/templates/options.adoc" as opts>
+<#import "/templates/links.adoc" as links>
+
+<@tmpl.guide
+title="Basic Keycloak Deployment"
+summary="How to install Keycloak using the Operator on Kubernetes or OpenShift">
+
+== Basic Keycloak Deployment
+In this guide we will show how to have a basic Keycloak Deployment on Kubernetes or OpenShift using the Operator.
+We assume that the Operator is correctly installed and running in the cluster namespace.
+
+=== Pre-requisites
+
+* Database
+* Hostname
+* TLS Certificate and associated keys
+
+==== Database
+
+A database should be available and accessible from the cluster namespace where you want to install Keycloak.
+Please refer to <@links.server id="db"/> for the list of supported databases.
+The Keycloak Operator does not manage the database and you need to provision it yourself, we suggest to verify your cloud provider offering or use a database Operator such as Crunchy[https://access.crunchydata.com/documentation/postgres-operator/latest/].
+
+
+For development purposes you can use an ephemeral Postgres pod installation.
+You can provision it using the following commands:
+
+[source,bash]
+----
+cat <<EOF >> example-postgres.yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: postgresql-db
+spec:
+  serviceName: postgresql-db-service
+  selector:
+    matchLabels:
+      app: postgresql-db
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: postgresql-db
+    spec:
+      containers:
+        - name: postgresql-db
+          image: postgres:latest
+          env:
+            - name: POSTGRES_PASSWORD
+              value: testpassword
+            - name: PGDATA
+              value: /data/pgdata
+            - name: POSTGRES_DB
+              value: keycloak
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres-db
+spec:
+  selector:
+    app: postgresql-db
+  type: LoadBalancer
+  ports:
+  - port: 5432
+    targetPort: 5432
+EOF
+kubectl|oc apply -f example-postgres.yaml
+----
+
+==== Hostname
+
+To have a production ready installation you need to provide the hostname that will be used to contact Keycloak.
+Please refer to <@links.server id="hostname"/> for the available configurations.
+
+For development purposes we will use from now on `test.keycloak.org`.
+
+==== TLS Certificate and key
+
+Please refer to Certification Authority of choiche to obtain the certificate and the key.
+
+For development purposes you can use this command to obtain a self-signed certificate:
+
+[source,bash]
+----
+openssl req -subj '/CN=test.keycloak.org/O=Test Keycloak./C=US' -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
+----
+
+and you should install it in the cluster namespace as a Secret by running:
+
+[source,bash]
+----
+kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem
+----
+
+=== Deploying Keycloak
+
+To deploy Keycloak you have to create a Custom Resource (CR from now on) shaped after the Keycloak Custom Resource Definition (CRD).
+
+We suggest you to first store the Database credentials in a separate Secret, you can do it for example by running:
+[source,bash]
+----
+kubectl create secret generic keycloak-db-secret \
+  --from-literal=username=[your_database_username] \
+  --from-literal=password=[your_database_password]
+----
+
+The Keycloak CRD allow you to customize several fields but, for a simple deployment you can use the following example:
+
+[source,bash]
+----
+cat <<EOF >> example-kc.yaml
+apiVersion: keycloak.org/v2alpha1
+kind: Keycloak
+metadata:
+  name: example-kc
+spec:
+  instances: 1
+  serverConfiguration:
+    - name: db
+      value: postgres
+    - name: db-url-host
+      value: postgres-db
+    - name: db-username
+      secret:
+        name: keycloak-db-secret
+        key: username
+    - name: db-password
+      secret:
+        name: keycloak-db-secret
+        key: password
+  hostname: test.keycloak.org
+  tlsSecret: example-tls-secret
+EOF
+kubectl|oc apply -f example-kc.yaml
+----
+
+And you can check that the Keycloak instance has been provisioned in the cluster by looking at the status of the created CR:
+
+[source,bash]
+----
+kubectl get keycloaks/example-kc -o go-template='{{range .status.conditions}}CONDITION: {{.type}}{{"\n"}}  STATUS: {{.status}}{{"\n"}}  MESSAGE: {{.message}}{{"\n"}}{{end}}'
+----
+
+When the Deployment is ready the output will look like the following:
+
+[source,bash]
+----
+CONDITION: Ready
+  STATUS: true
+  MESSAGE: 
+CONDITION: HasErrors
+  STATUS: false
+  MESSAGE: 
+CONDITION: RollingUpdate
+  STATUS: false
+  MESSAGE:
+----
+
+==== Accessing the Keycloak Deployment
+
+The Keycloak deployment is, by default, exposed through a basic nginx ingress and it will be accessible through the provided hostname.
+
+For debugging and development purposes we suggest you to directly connect to the Keycloak service using a port forward:
+
+[source,bash]
+----
+kubectl port-forward service/example-kc-service 8443:8443
+----
+
+</@tmpl.guide>