You can use the Operator to automate the installation of {project_name} by creating a Keycloak custom resource. When you use a custom resource to install {project_name}, you create the components and services that are described here and illustrated in the graphic that follows.
* `keycloak-db-secret` - Stores properties such as the database username, password, and external address (if you connect to an external database)
* `credentials-<CR-Name>` - Admin username and password to log into the {project_name} admin console (the `<CR-Name>` is based on the `Keycloak` custom resource name)
* `keycloak` - Keycloak deployment specification that is implemented as a StatefulSet with high availability support
* `keycloak-postgresql` - Starts a PostgreSQL database installation
* `keycloak-discovery` Service - Performs `JDBC_PING` discovery
* `keycloak` Service - Connects to {project_name} through HTTPS (HTTP is not supported)
* `keycloak-postgresql` Service - Connects an internal and external, if used, database instance
* `keycloak` Route - The URL for accessing the {project_name} admin console from OpenShift
ifeval::[{project_community}==true]
* `keycloak` Ingress - The URL for accessing the {project_name} admin console from Kubernetes
endif::[]
.How Operator components and services interact
image:{project_images}/operator-components.png[]
==== The Keycloak custom resource
The Keycloak custom resource is a YAML file that defines the parameters for installation. This file contains three properties.
* `instances` - controls the number of instances running in high availability mode.
* `externalAccess` - if the `enabled` is `True`, the Operator creates a route for OpenShift
ifeval::[{project_community}==true]
or an Ingress for Kubernetes
endif::[]
for the {project_name} cluster.
* `externalDatabase` - applies only if you want to connect an externally hosted database. That topic is covered in the xref:_external_database[external database] section of this guide.
You can update the YAML file and the changes appear in the {project_name} admin console, however changes to the admin console do not update the custom resource.
====
==== Creating a Keycloak custom resource on OpenShift
On OpenShift, you use the custom resource to create a route, which is the URL of the admin console, and find the secret, which holds the username and password for the admin console.
.Prerequisites
* You have a YAML file for this custom resource.
* You have cluster-admin permission or an equivalent level of permissions granted by an administrator.
ifeval::[{project_community}==true]
* If you want to start tracking all Operator activities now, install the monitoring application before you create this custom resource. See xref:_monitoring-operator[The Application Monitoring Operator].
endif::[]
.Procedure
. Create a route using your YAML file: `{create_cmd} -f <filename>.yaml -n <namespace>`. For example:
+
[source,bash,subs=+attributes]
----
ifeval::[{project_community}==true]
$ {create_cmd} -f keycloak.yaml -n keycloak
keycloak.keycloak.org/example-keycloak created
endif::[]
ifeval::[{project_product}==true]
$ {create_cmd} -f sso.yaml -n sso
keycloak.keycloak.org/example-sso created
endif::[]
----
+
A route is created in OpenShift.
. Log into the OpenShift web console.
. Select `Networking`, `Routes` and search for Keycloak.
+
.Routes screen in OpenShift web console
image:images/route-ocp.png[]
. On the screen with the Keycloak route, click the URL under `Location`.
+
The {project_name} admin console login screen appears.
+
.Admin console login screen
image:images/login-empty.png[]
. Locate the username and password for the admin console in the OpenShift web console; under `Workloads`, click `Secrets` and search for Keycloak.
. Enter the username and password into the admin console login screen.
+
.Admin console login screen
image:images/login-complete.png[]
+
You are now logged into an instance of {project_name} that was installed by a Keycloak custom resource. You are ready to create custom resources for realms, clients, and users.
==== Creating a Keycloak custom resource on Kubernetes
On Kubernetes, you use the custom resource to create an ingress, which is the IP address of the admin console, and find the secret, which holds the username and password for that console.
.Prerequisites
* You have a YAML file for this custom resource.
* You have cluster-admin permission or an equivalent level of permissions granted by an administrator.
.Procedure
. Create the ingress using your YAML file. `{create_cmd} -f <filename>.yaml -n <namespace>`. For example:
+
[source,bash,subs=+attributes]
----
$ {create_cmd} -f keycloak.yaml -n keycloak
keycloak.keycloak.org/example-keycloak created
----
. Find the ingress: `{create_cmd_brief} get ingress -n <cr_name>`. For example:
+
[source,bash,subs=+attributes]
----
$ {create_cmd_brief} get ingress -n example-keycloak
NAME HOSTS ADDRESS PORTS AGE
keycloak keycloak.redhat.com 192.0.2.0 80 3m
----
. Copy and paste the ADDRESS (the ingress) into a web browser.
+
The {project_name} admin console login screen appears.
+
.Admin console login screen
image:images/login-empty.png[]
. Locate the username and password.
+
[source,bash,subs=+attributes]
----
$ {create_cmd_brief} get secret credentials-<CR-Name> -o go-template='{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"\n"}}{{end}}'
----
. Enter the username and password in the admin console login screen.
+
.Admin console login screen
image:images/login-complete.png[]
+
You are now logged into an instance of {project_name} that was installed by a Keycloak custom resource. You are ready to create custom resources for realms, clients, and users.
+
.Admin console master realm
image:images/new_install_cr.png[]
endif::[]
.Results
After the Operator processes the custom resource, view the status with this command:
* Once the installation of {project_name} completes, you are ready to xref:_realm-cr[create a realm custom resource].
* If you have an external database, you can modify the Keycloak custom resource to support it. See xref:_external_database[Connecting to an external database].
