Basic Deployment using the Keycloak Operator
Co-authored-by: Václav Muzikář <vmuzikar@redhat.com>
This commit is contained in:
andreaTP
Bruno Oliveira da Silva
parent
44000caaf5
commit
e1bd96ea42
1 changed files with 174 additions and 0 deletions
174
docs/guides/src/main/operator/basic-deployment.adoc
Normal file
174
docs/guides/src/main/operator/basic-deployment.adoc
Normal file
|
|
@ -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>
|
||||
Loading…
Reference in a new issue