diff --git a/docs/guides/src/main/operator/basic-deployment.adoc b/docs/guides/src/main/operator/basic-deployment.adoc new file mode 100644 index 0000000000..3dd9a6f36b --- /dev/null +++ b/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 <> 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 <> 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 +---- + +