diff --git a/server_installation/images/clients.png b/server_installation/images/clients.png new file mode 100644 index 0000000000..29636e1fbc Binary files /dev/null and b/server_installation/images/clients.png differ diff --git a/server_installation/images/cr-code.png b/server_installation/images/cr-code.png new file mode 100644 index 0000000000..37dc856396 Binary files /dev/null and b/server_installation/images/cr-code.png differ diff --git a/server_installation/images/installed-namespace.png b/server_installation/images/installed-namespace.png new file mode 100644 index 0000000000..55642349c5 Binary files /dev/null and b/server_installation/images/installed-namespace.png differ diff --git a/server_installation/images/keycloak_installed_cr.png b/server_installation/images/keycloak_installed_cr.png new file mode 100644 index 0000000000..f03e96cc40 Binary files /dev/null and b/server_installation/images/keycloak_installed_cr.png differ diff --git a/server_installation/images/login-complete.png b/server_installation/images/login-complete.png new file mode 100644 index 0000000000..57263465b3 Binary files /dev/null and b/server_installation/images/login-complete.png differ diff --git a/server_installation/images/login-empty.png b/server_installation/images/login-empty.png new file mode 100644 index 0000000000..f84b8cacbe Binary files /dev/null and b/server_installation/images/login-empty.png differ diff --git a/server_installation/images/new_install_cr.png b/server_installation/images/new_install_cr.png new file mode 100644 index 0000000000..6d6ccd6e77 Binary files /dev/null and b/server_installation/images/new_install_cr.png differ diff --git a/server_installation/images/realms.png b/server_installation/images/realms.png new file mode 100644 index 0000000000..13b43bd76d Binary files /dev/null and b/server_installation/images/realms.png differ diff --git a/server_installation/images/route-ocp.png b/server_installation/images/route-ocp.png new file mode 100644 index 0000000000..5e71204dc6 Binary files /dev/null and b/server_installation/images/route-ocp.png differ diff --git a/server_installation/images/secrets-ocp.png b/server_installation/images/secrets-ocp.png new file mode 100644 index 0000000000..5dc6d84b9a Binary files /dev/null and b/server_installation/images/secrets-ocp.png differ diff --git a/server_installation/images/test-realm-cr.png b/server_installation/images/test-realm-cr.png new file mode 100644 index 0000000000..674d3b2cfc Binary files /dev/null and b/server_installation/images/test-realm-cr.png differ diff --git a/server_installation/images/user_list.png b/server_installation/images/user_list.png new file mode 100644 index 0000000000..4e2cb58c15 Binary files /dev/null and b/server_installation/images/user_list.png differ diff --git a/server_installation/keycloak-images/admin-console.png b/server_installation/keycloak-images/admin-console.png new file mode 100755 index 0000000000..f845508fca Binary files /dev/null and b/server_installation/keycloak-images/admin-console.png differ diff --git a/server_installation/keycloak-images/operator-application-monitoring-routes.png b/server_installation/keycloak-images/operator-application-monitoring-routes.png index 57dfa234c3..9f687ecf01 100644 Binary files a/server_installation/keycloak-images/operator-application-monitoring-routes.png and b/server_installation/keycloak-images/operator-application-monitoring-routes.png differ diff --git a/server_installation/keycloak-images/operator-components.png b/server_installation/keycloak-images/operator-components.png new file mode 100644 index 0000000000..f4bcf56607 Binary files /dev/null and b/server_installation/keycloak-images/operator-components.png differ diff --git a/server_installation/keycloak-images/operator-graphana-dashboard.png b/server_installation/keycloak-images/operator-graphana-dashboard.png index 63d0133acd..678853fea7 100644 Binary files a/server_installation/keycloak-images/operator-graphana-dashboard.png and b/server_installation/keycloak-images/operator-graphana-dashboard.png differ diff --git a/server_installation/keycloak-images/operator-openshift-operatorhub.png b/server_installation/keycloak-images/operator-openshift-operatorhub.png index 143963c29f..26b4482f90 100644 Binary files a/server_installation/keycloak-images/operator-openshift-operatorhub.png and b/server_installation/keycloak-images/operator-openshift-operatorhub.png differ diff --git a/server_installation/keycloak-images/operator-operatorhub-install.png b/server_installation/keycloak-images/operator-operatorhub-install.png index 9f309b0365..821fbe22ca 100644 Binary files a/server_installation/keycloak-images/operator-operatorhub-install.png and b/server_installation/keycloak-images/operator-operatorhub-install.png differ diff --git a/server_installation/keycloak-images/operator-prometheus-alerts.png b/server_installation/keycloak-images/operator-prometheus-alerts.png index d2df9bb002..0db98eb609 100644 Binary files a/server_installation/keycloak-images/operator-prometheus-alerts.png and b/server_installation/keycloak-images/operator-prometheus-alerts.png differ diff --git a/server_installation/keycloak-images/welcome.png b/server_installation/keycloak-images/welcome.png new file mode 100755 index 0000000000..b7040cf2c6 Binary files /dev/null and b/server_installation/keycloak-images/welcome.png differ diff --git a/server_installation/master-docinfo.xml b/server_installation/master-docinfo.xml index ca9c5a8405..78b5b59531 100644 --- a/server_installation/master-docinfo.xml +++ b/server_installation/master-docinfo.xml @@ -10,7 +10,7 @@ Red Hat Customer Content Services - Copyright 2019 Red Hat, Inc. + Copyright 2020 Red Hat, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at diff --git a/server_installation/rhsso-images/admin-console.png b/server_installation/rhsso-images/admin-console.png new file mode 100644 index 0000000000..f845508fca Binary files /dev/null and b/server_installation/rhsso-images/admin-console.png differ diff --git a/server_installation/rhsso-images/login-page.png b/server_installation/rhsso-images/login-page.png new file mode 100644 index 0000000000..c037cecfc7 Binary files /dev/null and b/server_installation/rhsso-images/login-page.png differ diff --git a/server_installation/rhsso-images/operator-components.png b/server_installation/rhsso-images/operator-components.png new file mode 100644 index 0000000000..d5c864d77d Binary files /dev/null and b/server_installation/rhsso-images/operator-components.png differ diff --git a/server_installation/rhsso-images/operator-olm-installation.png b/server_installation/rhsso-images/operator-olm-installation.png new file mode 100644 index 0000000000..09c1cf1510 Binary files /dev/null and b/server_installation/rhsso-images/operator-olm-installation.png differ diff --git a/server_installation/rhsso-images/operator-openshift-operatorhub.png b/server_installation/rhsso-images/operator-openshift-operatorhub.png new file mode 100644 index 0000000000..3283d265e0 Binary files /dev/null and b/server_installation/rhsso-images/operator-openshift-operatorhub.png differ diff --git a/server_installation/rhsso-images/operator-operatorhub-install.png b/server_installation/rhsso-images/operator-operatorhub-install.png new file mode 100644 index 0000000000..9f309b0365 Binary files /dev/null and b/server_installation/rhsso-images/operator-operatorhub-install.png differ diff --git a/server_installation/topics.adoc b/server_installation/topics.adoc index ed406a5808..aa0d318794 100644 --- a/server_installation/topics.adoc +++ b/server_installation/topics.adoc @@ -47,14 +47,16 @@ include::topics/cache/eviction.adoc[] include::topics/cache/replication.adoc[] include::topics/cache/disable.adoc[] include::topics/cache/clear.adoc[] -ifeval::[{project_community}==true] include::topics/operator.adoc[] include::topics/operator/installation.adoc[] +ifeval::[{project_community}==true] +include::topics/operator/monitoring-stack.adoc[] +endif::[] include::topics/operator/keycloak-cr.adoc[] include::topics/operator/keycloak-realm-cr.adoc[] include::topics/operator/keycloak-client-cr.adoc[] include::topics/operator/keycloak-user-cr.adoc[] -include::topics/operator/keycloak-backup-cr.adoc[] include::topics/operator/external-database.adoc[] -include::topics/operator/monitoring-stack.adoc[] -endif::[] \ No newline at end of file +include::topics/operator/keycloak-backup-cr.adoc[] +include::topics/operator/extensions.adoc[] +include::topics/operator/command-options.adoc[] diff --git a/server_installation/topics/operator.adoc b/server_installation/topics/operator.adoc index b236f981eb..ff4cfa812b 100644 --- a/server_installation/topics/operator.adoc +++ b/server_installation/topics/operator.adoc @@ -2,13 +2,27 @@ [[_operator]] == {project_operator} -{project_operator} has been designed to automate {project_name} administration in Kubernetes/OpenShift cluster. -It allows you to: +:tech_feature_name: The {project_name} Operator +:tech_feature_disabled: false +include::templates/techpreview.adoc[] -* Install Keycloak to a namespace -* Import Keycloak Realms -* Import Keycloak Clients -* Import Keycloak Users -* Create scheduled backups of the database -* Install Extensions +The {project_operator} automates {project_name} administration in +ifeval::[{project_community}==true] +Kubernetes or +endif::[] +Openshift. You use this Operator to create custom resources (CRs), which automate administrative tasks. For example, instead of creating a client or a user in the {project_name} admin console, you can create custom resources to perform those tasks. A custom resource is a YAML file that defines the parameters for the administrative task. +You can create custom resources to perform the following tasks: + +* xref:_keycloak_cr[Install {project_name}] +* xref:_realm-cr[Create realms] +* xref:_client-cr[Create clients] +* xref:_user-cr[Create users] +* xref:_external_database[Connect to an external database] +* xref:_backup-cr[Schedule database backups] +* xref:_operator-extensions[Install extensions and themes] + +[NOTE] +After you create custom resources for realms, clients, and users, you can manage them by using the {project_name} admin console or as custom resources using the `{create_cmd_brief}` command. However, you cannot use both methods, because the Operator performs a one way sync for custom resources that you modify. For example, if you modify a realm custom resource, the changes show up in the admin console. However, if you modify the realm using the admin console, those changes have no effect on the custom resource. + +Begin using the Operator by xref:_installing-operator[Installing the {project_operator} on a cluster]. diff --git a/server_installation/topics/operator/command-options.adoc b/server_installation/topics/operator/command-options.adoc new file mode 100644 index 0000000000..0823b14aad --- /dev/null +++ b/server_installation/topics/operator/command-options.adoc @@ -0,0 +1,25 @@ + +[[_command-options]] +=== Command options for managing custom resources + +After you create a custom request, you can edit it or delete using the `{create_cmd_brief}` command. + +* To edit a custom request, use this command: `{create_cmd_brief} edit ` +* To delete a custom request, use this command: `{create_cmd_brief} delete ` + +For example, to edit a realm custom request named `test-realm`, use this command: + +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} edit test-realm +---- + +A window opens where you can make changes. For example, you might change the name `arealm` to `demo-realm`. + +.Sample code for a custom resource +image:images/cr-code.png[] + +[NOTE] +==== +You can update the YAML file and changes appear in the {project_name} admin console, however changes to the admin console do not update the custom resource. +==== diff --git a/server_installation/topics/operator/extensions.adoc b/server_installation/topics/operator/extensions.adoc new file mode 100644 index 0000000000..14bd42d8bd --- /dev/null +++ b/server_installation/topics/operator/extensions.adoc @@ -0,0 +1,41 @@ + +[[_operator-extensions]] +=== Installing extensions and themes + +You can use the operator to install extensions and themes that you need for your company or organization. The extension or theme can be anything that {project_name} can consume. For example, you can add a metrics extension. You add the extension or theme to the Keycloak custom resource. + +.Example YAML file for a Keycloak custom resource +```yaml +apiVersion: keycloak.org/v1alpha1 +kind: Keycloak +metadata: + name: example-keycloak + labels: + app: sso +spec: + instances: 1 + extensions: + - + externalAccess: + enabled: True +``` + +.Prerequisites + +* You have a YAML file for the Keycloak custom resource. + +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + + +.Procedure + +. Edit the YAML file for the Keycloak custom resource: `{create_cmd_brief} edit ` + +. Add a line called `extensions:` after the `instances` line. + +. Add a URL to a JAR file for your custom extension or theme. + +. Save the file. + +The Operator downloads the extension or theme and installs it. + diff --git a/server_installation/topics/operator/external-database.adoc b/server_installation/topics/operator/external-database.adoc index 91aa15428b..829b0dd024 100644 --- a/server_installation/topics/operator/external-database.adoc +++ b/server_installation/topics/operator/external-database.adoc @@ -1,9 +1,10 @@ -=== External database support +[[_external_database]] +=== Connecting to an external database -Enabling external Postgresql database support requires creating `keycloak-db-secret` in the following form (note that values are Base64 encoded, see https://kubernetes.io/docs/concepts/configuration/secret/[Kubernetes Secrets manual]): +You can use the Operator to connect to an external PostgreSQL database by modifying the Keycloak custom resource and creating a `keycloak-db-secret` YAML file. Note that values are Base64 encoded. -.`keycloak-db-secret` Secret +.Example YAML file for `keycloak-db-secret` ```yaml apiVersion: v1 kind: Secret @@ -23,25 +24,25 @@ stringData: type: Opaque ``` -There are two properties specifically responsible for specifying external database hostname or IP address and its port: +The following properties set the hostname or IP address and port of the database. -* POSTGRES_EXTERNAL_ADDRESS - an IP address (or a Hostname) of the external database. This address needs to be resolvable from the perspective of a Kubernetes cluster. -* POSTGRES_EXTERNAL_PORT - (Optional) A database port. +* `POSTGRES_EXTERNAL_ADDRESS` - an IP address or a hostname of the external database. +ifeval::[{project_community}==true] +This address needs be resolvable in a Kubernetes cluster. +endif::[] +* `POSTGRES_EXTERNAL_PORT` - (Optional) A database port. -The other properties should to be set as follows: +The other properties work in the same way for a hosted or external database. Set them as follows: * `POSTGRES_DATABASE` - Database name to be used. * `POSTGRES_HOST` - The name of the `Service` used to communicate with a database. Typically `keycloak-postgresql`. * `POSTGRES_USERNAME` - Database username * `POSTGRES_PASSWORD` - Database password -* `POSTGRES_SUPERUSER` - Indicates, whether backups should assume running as super user. Typically `true`. +* `POSTGRES_SUPERUSER` - Indicates, whether backups should run as super user. Typically `true`. -The other properties remain the same for both operating modes (hosted Postgresql and an external one). +The Keycloak custom resource requires updates to enable external database support. -The Keycloak Custom Resource also needs to be updated to turn the external database support on. -Here's an example: - -.`Keycloak` Custom Resource with external database support +.Example YAML file for `Keycloak` custom resource that supports an external database ```yaml apiVersion: keycloak.org/v1alpha1 kind: Keycloak @@ -56,6 +57,83 @@ spec: instances: 1 ``` -==== Implementation details +.Prerequisites -{project_operator} allows you to use an external Postgresql database by modifying `-postgresql` Endpoints object. Typically, this object is maintained by Kubernetes, however it might be used to connect to an external service. See https://docs.openshift.com/container-platform/3.11/dev_guide/integrating_external_services.html[OpenShift manual] for more details. +* You have a YAML file for `keycloak-db-secret`. +* You have modified the Keycloak custom resource to set `externalDatabase` to `true`. +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +. Locate the secret for your PostgreSQL database: `{create_cmd_brief} get secret -o yaml`. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get secret keycloak-db-secret -o yaml +apiVersion: v1 +data + POSTGRES_DATABASE: cm9vdA== + POSTGRES_EXTERNAL_ADDRESS: MTcyLjE3LjAuMw== + POSTGRES_EXTERNAL_PORT: NTQzMg== +---- ++ +The `POSTGRES_EXTERNAL_ADDRESS` is in Base64 format. + +. Decode the value for the secret: `echo "" | base64 -decode`. For example: ++ +[source,bash,subs=+attributes] +---- +$ echo "MTcyLjE3LjAuMw==" | base64 -decode +192.0.2.3 +---- + +. Confirm that the decoded value matches the IP address for your database: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get pods -o wide +NAME READY STATUS RESTARTS AGE IP +keycloak-0 1/1 Running 0 13m 192.0.2.0 +keycloak-postgresql-c8vv27m 1/1 Running 0 24m 192.0.2.3 +---- + +. Confirm that `keycloak-postgresql` appears in a list of running services: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get svc +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +keycloak ClusterIP 203.0.113.0 8443/TCP 27m +keycloak-discovery ClusterIP None 8080/TCP 27m +keycloak-postgresql ClusterIP 203.0.113.1 5432/TCP 27m +---- ++ +The `keycloak-postgresql` service sends requests to a set of IP addresses in the backend. These IP addresses are called endpoints. + +. View the endpoints used by the `keycloak-postgresql` service to confirm that they use the IP addresses for your database: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get endpoints keycloak-postgresql +NAME ENDPOINTS AGE +keycloak-postgresql 192.0.2.3.5432 27m +---- + +. Confirm that {project_name} is running with the external database. This example shows that everything is running: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get pods +NAME READY STATUS RESTARTS AGE IP +keycloak-0 1/1 Running 0 26m 192.0.2.0 +keycloak-postgresql-c8vv27m 1/1 Running 0 36m 192.0.2.3 +---- + +ifeval::[{project_community}==true] +.Additional Resources + +* To back up your database using custom resources, see xref:_backup-cr[Scheduling database backups]. + + +* For more information on Base64 encoding, see the https://kubernetes.io/docs/concepts/configuration/secret/[Kubernetes Secrets manual]. +endif::[] diff --git a/server_installation/topics/operator/installation.adoc b/server_installation/topics/operator/installation.adoc index defe66ca4f..02760789d9 100644 --- a/server_installation/topics/operator/installation.adoc +++ b/server_installation/topics/operator/installation.adoc @@ -1,68 +1,154 @@ -=== Installing {project_operator} into OpenShift cluster +[[_installing-operator]] +=== Installing the {project_operator} on a cluster -There are two ways of running {project_operator} in Kubernetes/OpenShift cluster: +To install the {project_operator}, you can use: -* Using Operator Lifecycle Manager (OLM) -* Running manually +* xref:_install_by_olm[The Operator Lifecycle Manager (OLM)] +* xref:_install_by_command[Command line installation] -==== Using Operator Lifecycle Manager +[[_install_by_olm]] +==== Installing using the Operator Lifecycle Manager -In case of a newly installed OpenShift 4.x cluster, {project_operator} should already be available in -OperatorHub tab of the OpenShift administration panel (as shown in the image below). +ifeval::[{project_community}==true] +You can install the Operator on an xref:_openshift-olm[OpenShift] or xref:_kubernetes-olm[Kubernetes] cluster. +[[_openshift-olm]] +===== Installation on an OpenShift cluster +endif::[] + +.Prerequisites + +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +Perform this procedure on an OpenShift 4.4 cluster. + +. Open the OpenShift Container Platform web console. + +. In the left column, click `Operators, OperatorHub`. + +. Search for {project_name} Operator. ++ +.OperatorHub tab in OpenShift image:{project_images}/operator-openshift-operatorhub.png[] -If {project_operator} is not available, please navigate to https://operatorhub.io/operator/keycloak-operator, click `Install` button and follow the instructions on screen. - -image:{project_images}/operator-operatorhub-install.png[] - -TIP: For Kubernetes installation, please follow link:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/install/install.md[Operator Lifecycle Manager Installation Guide] - -Once {project_operator} is available in your cluster, click `Install` button and follow the instruction on -screen. - +. Click the {project_name} Operator icon. ++ +An Install page opens. ++ +.Operator Install page on OpenShift image:{project_images}/operator-olm-installation.png[] -For more information, navigate to link:https://docs.openshift.com/container-platform/4.2/operators/olm-what-operators-are.html[OpenShift Operators guide]. +. Click `Install`. -==== Running manually +. Select a namespace and click Subscribe. ++ +.Namespace selection in OpenShift +image:images/installed-namespace.png[] ++ +The Operator starts installing. -It is possible to run {project_operator} without Operator Lifecycle Manager. This requires running several -steps manually from link:{operatorRepo_link}[Github repo]: +.Additional resources -* Install all required Custom Resource Definitions by using the following command: +* When the Operator installation completes, you are ready to create your first custom resource. See xref:_keycloak_cr[{project_name} installation using a custom resource]. +ifeval::[{project_community}==true] +However, if you want to start tracking all Operator activities before creating custom resources, see the xref:_monitoring-operator[Application Monitoring Operator]. +endif::[] -```bash -kubectl apply -f deploy/crds/ -``` +* For more information on OpenShift Operators, see the link:https://docs.openshift.com/container-platform/4.4/operators/olm-what-operators-are.html[OpenShift Operators guide]. + +ifeval::[{project_community}==true] -* Create a new namespace (or reuse an existing one). For this example, we'll be using namespace `myproject`. +[[_kubernetes-olm]] +===== Installation on a Kubernetes cluster -```bash -kubectl create namespace myproject -``` +.Prerequisites -* Deploy Role, Role Binding and a Service Account for {project_operator}. +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. -```bash -kubectl apply -f deploy/role.yaml -n myproject -kubectl apply -f deploy/role_binding.yaml -n myproject -kubectl apply -f deploy/service_account.yaml -n myproject -``` +.Procedure -* Deploy {project_operator} +For a Kubernetes cluster, perform these steps. -```bash -kubectl apply -f deploy/operator.yaml -n myproject -``` +. Go to link:https://operatorhub.io/operator/keycloak-operator[Keycloak Operator on OperatorHub.io]. -* Validate if {project_operator} is running +. Click `Install`. -```bash -kubectl get deployment keycloak-operator +. Follow the instructions on the screen. ++ +.Operator Install page on Kubernetes +image:{project_images}/operator-operatorhub-install.png[] + +.Additional resources + +* When the Operator installation completes, you are ready to create your first custom resource. See xref:_keycloak_cr[{project_name} installation using a custom resource]. However, if you want to start tracking all Operator activities before creating custom resources, see the xref:_monitoring-operator[Application Monitoring Operator]. + +* For more information on a Kubernetes installation, see link:https://operatorhub.io/how-to-install-an-operator[How to install an Operator from OperatorHub.io]. + +endif::[] + +[[_install_by_command]] +==== Installing from the command line + +You can install the {project_operator} from the command line. + +.Prerequisites + +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +. Obtain the software to install from this location: link:{operatorRepo_link}[Github repo]. + +. Install all required custom resource definitions: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f deploy/crds/ +---- + +. Create a new namespace (or reuse an existing one) such as the namespace `myproject`: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} namespace myproject +---- + +. Deploy a role, role binding, and service account for the Operator: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f deploy/role.yaml -n myproject +$ {create_cmd} -f deploy/role_binding.yaml -n myproject +$ {create_cmd} -f deploy/service_account.yaml -n myproject +---- + +. Deploy the Operator: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f deploy/operator.yaml -n myproject +---- + +. Confirm that the Operator is running: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get deployment keycloak-operator NAME READY UP-TO-DATE AVAILABLE AGE keycloak-operator 1/1 1 1 41s -``` +---- + +.Additional resources + +* When the Operator installation completes, you are ready to create your first custom resource. See xref:_keycloak_cr[{project_name} installation using a custom resource]. +ifeval::[{project_community}==true] +However, if you want to start tracking all Operator activities before creating custom resources, see the xref:_monitoring-operator[Application Monitoring Operator]. + +* For more information on a Kubernetes installation, see link:https://operatorhub.io/how-to-install-an-operator[How to install an Operator from OperatorHub.io]. +endif::[] + +* For more information on OpenShift Operators, see the link:https://docs.openshift.com/container-platform/4.4/operators/olm-what-operators-are.html[OpenShift Operators guide]. -TIP: When deploying {project_operator} to an OpenShift cluster, `kubectl apply` commands can be replaced with their `oc create` counterparts. diff --git a/server_installation/topics/operator/keycloak-backup-cr.adoc b/server_installation/topics/operator/keycloak-backup-cr.adoc index 8c180924c5..1b101f5204 100644 --- a/server_installation/topics/operator/keycloak-backup-cr.adoc +++ b/server_installation/topics/operator/keycloak-backup-cr.adoc @@ -1,15 +1,28 @@ -=== KeycloakBackup Custom Resource +[[_backup-cr]] +=== Scheduling database backups -{project_operator} provides automatic backups with manual restore in 3 modes: +You can use the Operator to schedule automatic backups of the database as defined by custom resources. The custom resource triggers a backup job +ifeval::[{project_community}==true] +(or a `CronJob` in the case of Periodic Backups) +endif::[] +and reports back its status. -* One time backups to a local Persistent Volume. -* One time backups to Amazon S3 storage. -* Periodic backups to Amazon S3 storage. +ifeval::[{project_community}==true] +Two options exist to schedule backups: -The Operator uses `KeycloakBackup` Custom Resource (CR) to trigger a backup Job (or a `CronJob` in case of Periodic Backups) and reports back its status. The CR has the following structure: +* xref:_backups-cr-aws[Backing up to AWS S3 storage] +* xref:_backups-local-cr[Backing up to local storage] + +If you have AWS S3 storage, you can perform a one-time backup or periodic backups. If you do not have AWS S3 storage, you can back up to local storage. + +[[_backups-cr-aws]] +==== Backing up to AWS S3 storage + +You can back up your database to AWS S3 storage one time or periodically. To back up your data periodically, enter a valid `CronJob` into the `schedule`. + +For AWS S3 storage, you create a YAML file for the backup custom resource and a YAML file for the AWS secret. The backup custom resource requires a YAML file with the following structure: -.`KeycloakBackup` Custom Resource ```yaml apiVersion: keycloak.org/v1alpha1 kind: KeycloakBackup @@ -18,12 +31,14 @@ metadata: spec: aws: # Optional - used only for Periodic Backups. - # Follows usual crond syntax (e.g. use "0 1 * * *") to perform the backup every day at 1 AM. + # Follows usual crond syntax (for example, use "0 1 * * *" to perform the backup every day at 1 AM.) schedule: # Required - the name of the secret containing the credentials to access the S3 storage credentialsSecretName: ``` +The AWS secret requires a YAML file with the following structure: + .AWS S3 `Secret` ```yaml apiVersion: v1 @@ -37,74 +52,148 @@ stringData: AWS_SECRET_ACCESS_KEY: ``` -IMPORTANT: The above secret name needs to match the one referred in the `KeycloakBackup` Custom Resource. +.Prerequisites -Once the `KeycloakBackup` Custom Resource is created, {project_operator} will create a corresponding Job to back up the PostgreSQL database. The status of the backup is reported in the `status` field. -Here's an example: +* Your Backup custom resource YAML file includes a `credentialsSecretName` that references a `Secret` containing AWS S3 credentials. -.`KeycloakBackup` Status -```yaml -Name: example-keycloakbackup -Namespace: keycloak -Labels: -Annotations: -API Version: keycloak.org/v1alpha1 -Kind: KeycloakBackup -Metadata: - Creation Timestamp: 2019-10-31T08:13:10Z - Generation: 1 - Resource Version: 110940 - Self Link: /apis/keycloak.org/v1alpha1/namespaces/keycloak/keycloakbackups/example-keycloakbackup - UID: 0ea2e038-c328-48a0-8d5a-52acbc826577 -Status: - Message: - Phase: created - Ready: true - Secondary Resources: - Job: - example-keycloakbackup - Persistent Volume Claim: - keycloak-backup-example-keycloakbackup -``` +* Your `KeycloakBackup` custom resource has `aws` sub-properties. -==== Backups to AWS S3 +* You have a YAML file for the AWS S3 Secret that includes a `` that matches the one identified in the backup custom resource. -In order to create Backups uploaded to S3 storage, you need to create a `KeycloakBackup` Custom Resource with `aws` sub-properties. +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. -IMPORTANT: The `credentialsSecretName` field is required and needs to contain a valid reference to a `Secret` containing AWS S3 credentials. -If the `schedule` contains valid `CronJob` schedule definition, the Operator will backup your data periodically. +.Procedure -==== Backups to a Local Storage +. Create the secret with credentials: `{create_cmd} -f .yaml`. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f secret.yaml +keycloak.keycloak.org/aws_s3_secret created +---- -{project_operator} can also create a backup to a local Persistent Volume. In order to do it, you need to create a `KeycloakBackup` Custom Resource without `aws` sub-properties. Here's an example: +. Create a backup job: `{create_cmd} -f .yaml`. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f aws_one-time-backup.yaml +keycloak.keycloak.org/aws_s3_backup created +---- +. View a list of backup jobs: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get jobs +NAME COMPLETIONS DURATION AGE +aws_s3_backup 0/1 6s 6s +---- + +. View the list of executed backup jobs. ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get pods +NAME READY STATUS RESTARTS AGE +aws_s3_backup-5b4rfdd 0/1 Completed 0 24s +keycloak-0 1/1 Running 0 52m +keycloak-postgresql-c824c6-vv27m 1/1 Running 0 71m +---- + +. View the log of your completed backup job: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} logs aws_s3_backup-5b4rf +==> Component data dump completed +. +. +. +. +[source,bash,subs=+attributes] +---- + +The status of the backup job also appears in the AWS console. + +[[_backups-local-cr]] +==== Backing up to Local Storage + +endif::[] +You can use Operator to create a backup job that performs a one-time backup to a local Persistent Volume. + +.Example YAML file for a Backup custom resource ```yaml apiVersion: keycloak.org/v1alpha1 kind: KeycloakBackup metadata: - name: + name: test-backup ``` -{project_operator} will create a new `PersistentVolumeClaim` with the following naming scheme: +.Prerequisites - keycloak-backup- +* You have a YAML file for this custom resource. +ifeval::[{project_community}==true] +Be sure to omit the `aws` sub-properties from this file. +endif::[] -It is a good practice to create a corresponding `PersistentVolume` for the upcoming backups upfront and use `claimRef` to reserve it only for `PersistentVolumeClaim` created by the Keycloak Operator (see https://docs.okd.io/3.6/dev_guide/persistent_volumes.html#persistent-volumes-volumes-and-claim-prebinding[OKD manual for more details]). +* You have a `PersistentVolume` with a `claimRef` to reserve it only for a `PersistentVolumeClaim` created by the {project_name} Operator. -==== Automatic Restore +.Procedure -WARNING: This is not implemented! +. Create a backup job: `{create_cmd} -f `. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f one-time-backup.yaml +keycloak.keycloak.org/test-backup +---- ++ +The Operator creates a `PersistentVolumeClaim` with the following naming scheme: `Keycloak-backup-`. -One of the design goals of {project_name} Backups is to maintain one-to-one relationship between -`KeycloakBackup` object and a physical copy of the data. This relationship is then used to restore the data. All you need to do is to set the `restore` flag in the `KeycloakBackup` to true: +. View a list of volumes: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get pvc +NAME STATUS VOLUME +keycloak-backup-test-backup Bound pvc-e242-ew022d5-093q-3134n-41-adff +keycloak-postresql-claim Bound pvc-e242-vs29202-9bcd7-093q-31-zadj +---- + +. View a list of backup jobs: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get jobs +NAME COMPLETIONS DURATION AGE +test-backup 0/1 6s 6s +---- + +. View the list of executed backup jobs: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get pods +NAME READY STATUS RESTARTS AGE +test-backup-5b4rf 0/1 Completed 0 24s +keycloak-0 1/1 Running 0 52m +keycloak-postgresql-c824c6-vv27m 1/1 Running 0 71m +---- + +. View the log of your completed backup job: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} logs test-backup-5b4rf +==> Component data dump completed +. +. +. +. +---- + +.Additional resources + +* For more details on persistent volumes, see link:https://docs.openshift.com/container-platform/4.4/storage/understanding-persistent-storage.html[Understanding persistent storage]. -.`KeycloakBackup` with restore -```yaml -apiVersion: keycloak.org/v1alpha1 -kind: KeycloakBackup -metadata: - name: -spec: - restore: true -``` diff --git a/server_installation/topics/operator/keycloak-client-cr.adoc b/server_installation/topics/operator/keycloak-client-cr.adoc index 3000d50260..c48885a34d 100644 --- a/server_installation/topics/operator/keycloak-client-cr.adoc +++ b/server_installation/topics/operator/keycloak-client-cr.adoc @@ -1,20 +1,26 @@ -=== KeycloakClient Custom Resource +[[_client-cr]] +=== Creating a client custom resource -{project_operator} allows application developers to represent Keycloak Clients as Custom Resources: +You can use the Operator to create clients in {project_name} as defined by a custom resource. You define the properties of the realm in a YAML file. -.`KeycloakClient` Custom Resource +[NOTE] +==== +You can update the YAML file and changes appear in the {project_name} admin console, however changes to the admin console do not update the custom resource. +==== + +.Example YAML file for a Client custom resource ```yaml apiVersion: keycloak.org/v1alpha1 kind: KeycloakClient metadata: - name: + name: example-client labels: app: sso spec: realmSelector: matchLabels: - app: + app: client: # auto-generated if not supplied #id: 123 @@ -24,13 +30,50 @@ spec: # other properties of Keycloak Client ``` -TIP: Note, that `realmSelector` needs to match labels of an existing `KeycloakRealm` Custom Resource. +.Prerequisites -NOTE: {project_operator} synchronizes all the changes made to the Custom Resource with a running {project_name} instance. No manual changes via Keycloak Admin Console are allowed. +* You have a YAML file for this custom resource. -Once {project_operator} reconciles the Custom Resource, it reports the status back: +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. -.`KeycloakClient` Custom Resource Status +.Procedure + +. Use this command on the YAML file that you created: `{create_cmd} -f .yaml`. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f initial_client.yaml +keycloak.keycloak.org/example-client created +---- + +. Log into the {project_name} admin console for the related instance of {project_name}. + +. Click Clients. ++ +The new client appears in the list of clients. ++ +image:images/clients.png[] + +.Results +After a client is created, the Operator creates a Secret containing the `Client ID` and the client's secret using the following naming pattern: `keycloak-client-secret-`. For example: + +.Client's Secret +```yaml +apiVersion: v1 +data: + CLIENT_ID: + CLIENT_SECRET: +kind: Secret +``` + +After the Operator processes the custom resource, view the status with this command: + +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} describe keycloak +---- + +.Client custom resource Status ```yaml Name: client-secret Namespace: keycloak @@ -55,13 +98,6 @@ Status: Events: ``` -Once a Client is created, {project_operator} creates a Secret with, containing both `Client ID` as well as the client's secret using the following naming pattern: `keycloak-client-secret-`. Here's an example: +.Additional resources -.`KeycloakClient`'s Secret -``` -apiVersion: v1 -data: - CLIENT_ID: - CLIENT_SECRET: -kind: Secret -``` +* When the client creation completes, you are ready to xref:_user-cr[create a user custom resource]. \ No newline at end of file diff --git a/server_installation/topics/operator/keycloak-cr.adoc b/server_installation/topics/operator/keycloak-cr.adoc index 8a2022767b..1709c2af35 100644 --- a/server_installation/topics/operator/keycloak-cr.adoc +++ b/server_installation/topics/operator/keycloak-cr.adoc @@ -1,14 +1,47 @@ -=== Keycloak Custom Resource +[[_keycloak_cr]] +=== {project_name} installation using a custom resource -The {project_operator} allows users to manage {project_name} clusters by using Keycloak Custom Resources: +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` Custom Resource +* `keycloak-db-secret` - Stores properties such as the database username, password, and external address (if you connect to an external database) +* `credentials-` - Admin username and password to log into the {project_name} admin console (the `` 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. + +.Example YAML file for a Keycloak custom resource ```yaml apiVersion: keycloak.org/v1alpha1 kind: Keycloak metadata: +ifeval::[{project_community}==true] name: example-keycloak +endif::[] +ifeval::[{project_product}==true] + name: example-sso +endif::[] labels: app: sso spec: @@ -17,14 +50,144 @@ spec: enabled: True ``` -The `Spec` contains three properties (two of them are listed above and the external database has been covered in the other paragraphs of this manual): +[NOTE] +==== +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. +==== -* `instances` - controls the number of instances running in HA mode -* `externalAccess` - if the `enabled` flag is set to `True`, depending on the types available in the cluster {project_operator} will create a Route or an Ingress for {project_name} cluster. +==== Creating a Keycloak custom resource on OpenShift -Once {project_operator} reconciles the Custom Resource, it reports the status back: +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. -.`Keycloak` Custom Resource Status +.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 .yaml -n `. 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. ++ +.Secrets screen in OpenShift web console +image:images/secrets-ocp.png[] + +. 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. ++ +.{project_name} master realm +image:images/new_install_cr.png[] + +. Check the status of the custom resource: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} describe keycloak +---- + +ifeval::[{project_community}==true] +==== 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 .yaml -n `. 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 `. 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- -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: + +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} describe keycloak +---- + +.Keycloak custom resource Status ```yaml Name: example-keycloak Namespace: keycloak @@ -65,3 +228,9 @@ Status: Version: Events: ``` + +.Additional resources + +* 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]. diff --git a/server_installation/topics/operator/keycloak-realm-cr.adoc b/server_installation/topics/operator/keycloak-realm-cr.adoc index 8e859ff14f..bc8ea2d6c9 100644 --- a/server_installation/topics/operator/keycloak-realm-cr.adoc +++ b/server_installation/topics/operator/keycloak-realm-cr.adoc @@ -1,14 +1,20 @@ -=== KeycloakRealm Custom Resource +[[_realm-cr]] +=== Creating a realm custom resource -The {project_operator} allows application developers to represent {project_name} Realms as Custom Resources: +You can use the Operator to create realms in {project_name} as defined by a custom resource. You define the properties of the realm custom resource in a YAML file. -.`KeycloakRealm` Custom Resource +[NOTE] +==== +You can update the YAML file and changes appear in the {project_name} admin console, however changes to the admin console do not update the custom resource. +==== + +.Example YAML file for a `Realm` custom resource ```yaml apiVersion: keycloak.org/v1alpha1 kind: KeycloakRealm metadata: - name: example-keycloakrealm + name: test labels: app: sso spec: @@ -22,13 +28,43 @@ spec: app: sso ``` -IMPORTANT: Note, that `instanceSelector` needs to match labels of an existing `Keycloak` Custom Resource. +.Prerequisites -NOTE: {project_operator} synchronizes all the changes made to the Custom Resource with a running {project_name} instance. No manual changes via {project_name} Admin Console are allowed. +* You have a YAML file for this custom resource. -Once {project_operator} reconciles the Custom Resource, it reports the status back: +* In the YAML file, the `app` under `instanceSelector` matches the label of a Keycloak custom resource. Matching these values ensures that you create the realm in the right instance of {project_name}. -.`KeycloakRealm` Custom Resource Status +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +. Use this command on the YAML file that you created: `{create_cmd} -f .yaml`. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f initial_realm.yaml +keycloak.keycloak.org/test created +---- + +. Log into the admin console for the related instance of {project_name}. + +. Click Select Realm and locate the realm that you created. ++ +The new realm opens. ++ +.Admin console master realm +image:images/test-realm-cr.png[] + +.Results + +After the Operator processes the custom resource, view the status with this command: + +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} describe keycloak +---- + +.Realm custom resource status ```yaml Name: example-keycloakrealm Namespace: keycloak @@ -61,3 +97,7 @@ Status: Events: ``` + +Additional resources + +* When the realm creation completes, you are ready to xref:_client-cr[create a client custom resource]. \ No newline at end of file diff --git a/server_installation/topics/operator/keycloak-user-cr.adoc b/server_installation/topics/operator/keycloak-user-cr.adoc index fcc8133f3a..385f5b8871 100644 --- a/server_installation/topics/operator/keycloak-user-cr.adoc +++ b/server_installation/topics/operator/keycloak-user-cr.adoc @@ -1,14 +1,20 @@ -=== KeycloakUser Custom Resource +[[_user-cr]] +=== Creating a user custom resource -{project_name} Users can be represented as Custom Resources in {project_operator}: +You can use the Operator to create users in {project_name} as defined by a custom resource. You define the properties of the user custom resource in a YAML file. -.`KeycloakUser` Custom Resource +[NOTE] +==== +You can update properties, except for the password, in the YAML file and changes appear in the {project_name} admin console, however changes to the admin console do not update the custom resource. +==== + +.Example YAML file for a user custom resource ```yaml apiVersion: keycloak.org/v1alpha1 kind: KeycloakUser metadata: - name: example-realm-user + name: example-user spec: user: username: "realm_user" @@ -29,13 +35,57 @@ spec: app: sso ``` -IMPORTANT: Note, that `realmSelector` needs to match labels of an existing `KeycloakRealm` Custom Resource. +.Prerequisites -NOTE: {project_operator} synchronizes all the changes made to the Custom Resource with a running {project_name} instance. No manual changes via {project_name} Admin Console are allowed. +* You have a YAML file for this custom resource. -Once {project_operator} reconciles the Custom Resource, it reports the status back: +* The `realmSelector` matches the labels of an existing realm custom resource. -.`KeycloakUser` Custom Resource Status +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +. Use this command on the YAML file that you created: `{create_cmd} -f .yaml`. For example: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f initial_user.yaml +keycloak.keycloak.org/example-user created +---- + +. Log into the admin console for the related instance of {project_name}. + +. Click Users. + +. Search for the user that you defined in the YAML file. ++ +The user is in the list. ++ +image:images/user_list.png[] + +.Results + +After a user is created, the Operator creates a Secret containing the both username and password using the +following naming pattern: `credential---`. Here's an example: + +.`KeycloakUser` Secret +```yaml +kind: Secret +apiVersion: v1 +data: + password: + username: +type: Opaque +``` + +Once the Operator processes the custom resource, view the status with this command: + +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} describe keycloak +---- + +.User custom resource Status ```yaml Name: example-realm-user Namespace: keycloak @@ -62,15 +112,8 @@ Status: Events: ``` -Once a User is created, {project_operator} creates a Secret containing both username and password using the -following naming pattern: `credential---`. Here's an example: +.Additional resources -.`KeycloakUser` Secret -``` -kind: Secret -apiVersion: v1 -data: - password: - username: -type: Opaque -``` +* 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]. + +* To back up your database using custom resources, see xref:_backup-cr[schedule database backups]. diff --git a/server_installation/topics/operator/monitoring-stack.adoc b/server_installation/topics/operator/monitoring-stack.adoc index e57bdf4b04..d868476004 100644 --- a/server_installation/topics/operator/monitoring-stack.adoc +++ b/server_installation/topics/operator/monitoring-stack.adoc @@ -1,31 +1,56 @@ -=== Monitoring Stack +[[_monitoring-operator]] +=== The {application_monitoring_operator} -{project_operator} integrates with {application_monitoring_operator} providing Graphana Dashboard and Prometheus Alerts. The integration is seamless and doesn't require any action from the user. However, {application_monitoring_operator} needs to be properly installed in the cluster. +Before using the Operator to install {project_name} or create components, we recommend that you install the {application_monitoring_operator}, which that tracks Operator activity. To view metrics for the Operator, you can use the Grafana Dashboard and Prometheus Alerts from the {application_monitoring_operator}. For example, you can view metrics such as the number of controller runtime reconciliation loops, the reconcile loop time, and errors. -==== Installing {application_monitoring_operator} +The {project_operator} integration with the {application_monitoring_operator} requires no action. You only need to install the {application_monitoring_operator} in the cluster. -Prior to running {project_operator} it is recommended to install {application_monitoring_operator} by following the link:{application_monitoring_operator_installation_link}[documentation]. After {application_monitoring_operator} is up and running, you need to annotate the namespace used for {project_operator} installation. Here's an example: +==== Installing the {application_monitoring_operator} -.Annotating namespace for monitoring -```bash -oc label namespace monitoring-key=middleware -``` +.Prerequisites -Once the {application_monitoring_operator} is installed and running, also the corresponding namespace is annotated for monitoring, you can search for Prometheus and Graphana route in `application-monitoring` namespace: +* The {project_operator} is installed. +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +. Install the {application_monitoring_operator} by using the link:{application_monitoring_operator_installation_link}[documentation]. + +. Annotate the namespace used for the {project_operator} installation. For example: ++ +[source,bash,subs=+attributes] +---- +{create_cmd_brief} label namespace monitoring-key=middleware +---- + +. Log into the OpenShift web console. + +. Confirm monitoring is working by searching for Prometheus and Grafana route in the `application-monitoring` namespace. ++ +.Routes in OpenShift web console image:{project_images}/operator-application-monitoring-routes.png[] -==== Graphana Dashboard +==== Viewing Operator Metrics -{project_operator} installs a pre-defined Graphana Dashboard. Here's how it looks like: +Grafana and Promotheus each provide graphical information about Operator activities. +* The Operator installs a pre-defined Grafana Dashboard as shown here: ++ +.Grafana Dashboard image:{project_images}/operator-graphana-dashboard.png[] ++ +[NOTE] +==== +If you make customizations, we recommend that you clone the Grafana Dashboard so that your changes are not overwritten during an upgrade. +==== -NOTE: Graphana Dashboard is likely to be changed in future releases. If you need any customizations, please clone it and adjust to your needs. - -==== Prometheus Alerts - -{project_operator} installs a set of pre-defined Prometheus Alerts. Here's how they look like: - +* The Operator installs a set of pre-defined Prometheus Alerts as shown here: ++ +.Prometheus Alerts image:{project_images}/operator-prometheus-alerts.png[] + +.Additional resources + +For more information, see link:https://docs.openshift.com/container-platform/latest/monitoring/cluster_monitoring/prometheus-alertmanager-and-grafana.html[Accessing Prometheus, Alertmanager, and Grafana]. \ No newline at end of file diff --git a/topics/templates/document-attributes-community.adoc b/topics/templates/document-attributes-community.adoc index 9235419326..f100e2660f 100644 --- a/topics/templates/document-attributes-community.adoc +++ b/topics/templates/document-attributes-community.adoc @@ -24,6 +24,8 @@ endif::[] :operatorRepo_link: https://github.com/keycloak/keycloak-operator :application_monitoring_operator: Application Monitoring Operator :application_monitoring_operator_installation_link: https://github.com/integr8ly/application-monitoring-operator#installation +:create_cmd: kubectl apply +:create_cmd_brief: kubectl :quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts :quickstartRepo_name: Keycloak Quickstarts Repository diff --git a/topics/templates/document-attributes-product.adoc b/topics/templates/document-attributes-product.adoc index 1b1e0a67d1..a22d6d58c0 100644 --- a/topics/templates/document-attributes-product.adoc +++ b/topics/templates/document-attributes-product.adoc @@ -20,6 +20,8 @@ :operatorRepo_link: https://github.com/keycloak/keycloak-operator :application_monitoring_operator: Red Hat Managed Integration (RHMI) Application Monitoring Operator :application_monitoring_operator_installation_link: https://github.com/integr8ly/application-monitoring-operator#installation +:create_cmd: oc create +:create_cmd_brief: oc :project_dirref: RHSSO_HOME diff --git a/xref b/xref new file mode 100644 index 0000000000..b9913c59a8 --- /dev/null +++ b/xref @@ -0,0 +1,152 @@ + +[[_installing-operator]] +=== Installing the {project_operator} on a cluster + +To install the {project_operator}, you can use: + +* xref:_install_by_olm[The Operator Lifecycle Manager (OLM)] +* xref:_install_by_command[Command line installation] + +[[_install_by_olm]] +==== Installing using the Operator Lifecycle Manager + +ifeval::[{project_community}==true] +You can install the Operator on an xref:_openshift-olm[OpenShift] or xref:_kubernetes-olm[Kubernetes] cluster. + +[[_openshift-olm]] +===== Installation on an OpenShift cluster +endif::[] + +.Prerequisites + +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +Perform this procedure on an OpenShift 4.4 cluster. + +. Open the OpenShift Container Platform web console. + +. In the left column, click `Operators, OperatorHub`. + +. Search for {project_name} Operator. ++ +.OperatorHub tab in OpenShift +image:{project_images}/operator-openshift-operatorhub.png[] + +. Click the {project_name} Operator icon. ++ +An Install page opens. ++ +.Operator Install page on OpenShift +image:{project_images}/operator-olm-installation.png[] + +. Click `Install`. + +. Select a namespace and click Subscribe. ++ +.Namespace selection in OpenShift +image:images/installed-namespace.png[] ++ +The Operator starts installing. + +When the Operator installation completes, you are ready to create custom resources to install {project_name}, create realms, and perform other adminstrative tasks. + +ifeval::[{project_community}==true] + +[[_kubernetes-olm]] +===== Installation on a Kubernetes cluster + +.Prerequisites + +* You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +For a Kubernetes cluster, perform these steps. + +. Go to link:https://operatorhub.io/operator/keycloak-operator[Keycloak Operator on OperatorHub.io]. + +. Click `Install`. + +. Follow the instructions on the screen. ++ +.Operator Install page on Kubernetes +image:{project_images}/operator-operatorhub-install.png[] + +When the Operator installation completes, you are ready to create custom resources to install {project_name}, create realms, and perform other adminstrative tasks. +endif::[] + +.Additional Resources + +ifeval::[{project_community}==true] +* For more information on a Kubernetes installation, see link:https://operatorhub.io/how-to-install-an-operator[How to install an Operator from OperatorHub.io]. + +* To track what you install and create with the operator, you can now set up a monitoring application. See xref:_monitoring-operator[The Application Monitoring Operator]. +endif::[] + +* For more information on OpenShift Operators, see the link:https://docs.openshift.com/container-platform/4.4/operators/olm-what-operators-are.html[OpenShift Operators guide]. + +* For more information on OpenShift installation, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.4/html/installing/index[Installing and Configuring OpenShift Container Platform clusters]. + +[[_install_by_command]] +==== Installing from the command line + +You can install the {project_operator} from the command line. + +.Prerequisites + +You have cluster-admin permission or an equivalent level of permissions granted by an administrator. + +.Procedure + +. Obtain the software to install from this location: link:{operatorRepo_link}[Github repo]. + +. Install all required custom resource definitions: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f deploy/crds/ +---- + +. Create a new namespace (or reuse an existing one) such as the namespace `myproject`: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} namespace myproject +---- + +. Deploy a role, role binding, and service account for the Operator: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f deploy/role.yaml -n myproject +$ {create_cmd} -f deploy/role_binding.yaml -n myproject +$ {create_cmd} -f deploy/service_account.yaml -n myproject +---- + +. Deploy the Operator: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd} -f deploy/operator.yaml -n myproject +---- + +. Confirm that the Operator is running: ++ +[source,bash,subs=+attributes] +---- +$ {create_cmd_brief} get deployment keycloak-operator +NAME READY UP-TO-DATE AVAILABLE AGE +keycloak-operator 1/1 1 1 41s +---- + +.Additional resources + +* To create your first custom resource, see xref:_keycloak_cr[{project_name} installation using a custom resource]. +ifeval::[{project_community}==true] +* If you want to start tracking all Operator activities before creating custom resources, see the xref:_monitoring-operator[Application Monitoring Operator]. +endif::[] + + +