Chapter 4. Migrating Templates deployments on Openshift OpenShift templates were deprecated and removed from the Red Hat build of Keycloak container images. Using the Operator is the recommended alternative for deploying Red Hat build of Keycloak on OpenShift. Note OpenShift 3.x is no longer supported. You will generally need to create a Keycloak CR (of the Red Hat build of Keycloak Operator) that references an externally managed database. The PostgreSQL database with this template is managed by a DeploymentConfig. You initially retain the application_name-postgresql DeploymentConfig that was created by the template. The PostgreSQL database instance created by the DeploymentConfig will be usable by the Red Hat build of Keycloak Operator. This guide does not include directions for migrating from this instance to a self-managed database, either by an operator or your cloud provider. The Red Hat build of Keycloak Operator does not manage a database and it is required to have a database provisioned and managed separately. 4.1. Migrating deployments with the internal H2 database The following are the affected templates: sso76-ocp3-https sso76-ocp4-https sso76-ocp3-x509-https sso76-ocp4-x509-https These templates rely upon the devel database and are not supported for production use. 4.2. Migrating deployments with ephemeral PostgreSQL database The following are the affected templates: sso76-ocp3-postgresql sso76-ocp4-postgresql This template creates a PostgreSQL database without persistent storage, which is only recommended for development purposes. 4.3. Migrating deployments with persistent PostgreSQL database The following are the affected templates: sso76-ocp3-postgresql-persistent sso76-ocp4-postgresql-persistent sso76-ocp3-x509-postgresql-persistent sso76-ocp4-x509-postgresql-persistent 4.3.1. Prerequisites The instance of Red Hat Single Sign-On 7.6 was shut down so that it does not use the same database instance that will be used by Red Hat build of Keycloak . Database backup was created. You reviewed the Release Notes . 4.4. Migration process Install Red Hat build of Keycloak Operator to the namespace. Create new CRs and related Secrets. Manually migrate your template based Red Hat Single Sign-On 7.6 configuration to your new Red Hat build of Keycloak CR. See the following examples for suggested mappings between Template parameters and Keycloak CR fields. The following examples compare a Red Hat build of Keycloak Operator CR to the DeploymentConfig that was previously created by a Red Hat Single Sign-On 7.6 Template. Operator CR for Red Hat build of Keycloak apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: rhbk spec: instances: 1 db: vendor: postgres host: postgres-db usernameSecret: name: keycloak-db-secret key: username passwordSecret: name: keycloak-db-secret key: password http: tlsSecret: sso-x509-https-secret DeploymentConfig for Red Hat Single Sign-On 7.6 apiVersion: apps.openshift.io/v1 kind: DeploymentConfig metadata: name: rhsso spec: replicas: 1 template: spec: volumes: - name: sso-x509-https-volume secret: secretName: sso-x509-https-secret defaultMode: 420 containers: volumeMounts: - name: sso-x509-https-volume readOnly: true env: - name: DB_SERVICE_PREFIX_MAPPING value: postgres-db=DB - name: DB_USERNAME value: username - name: DB_PASSWORD value: password The following tables refer to fields of Keycloak CR by a JSON path notation. For example, .spec refers to the spec field. Note that spec.unsupported is a Technology Preview field. It is more an indication that eventually that functionality will be achievable by other CR fields. Parameters marked in bold are supported by both the passthrough and reencrypt templates. 4.4.1. General Parameter Migration Red Hat Single Sign-On 7.6 Red Hat build of Keycloak 24.0 APPLICATION_NAME .metadata.name IMAGE_STREAM_NAMESPACE N/A - the image is controlled by the operator or you main use spec.image to specify a custom image SSO_ADMIN_USERNAME No direct setting, defaults to admin SSO_ADMIN_PASSWORD N/A - created by the operator during the initial reconciliation MEMORY_LIMIT .spec.unsupported.podTemplate.spec.containers[0].resources.limits['memory'] SSO_SERVICE_PASSWORD , SSO_SERVICE_USERNAME No longer used. SSO_TRUSTSTORE , SSO_TRUSTSTORE_PASSWORD , SSO_TRUSTSTORE_SECRET .spec.truststores Notice that truststores must not be password protected. SSO_REALM Not needed if you are reusing the existing database. An alternative is the RealmImport CR. 4.4.2. Database Deployment Parameter Migration POSTGRESQL_IMAGE_STREAM_TAG , POSTGRESQL_MAX_CONNECTIONS , VOLUME_CAPACITY and POSTGRESQL_SHARED_BUFFERS will need to be migrated to whatever replacement you have chosen creating the database deployment. 4.4.3. Database Connection Parameter Migration Red Hat Single Sign-On 7.6 Red Hat build of Keycloak 24.0 DB_VENDOR .spec.db.vendor - will need to be set to PostgreSQL if PostgreSQL is still being used DB_DATABASE .spec.db.database DB_MIN_POOL_SIZE .spec.db.poolMinSize DB_MAX_POOL_SIZE .spec.db.maxPoolSize DB_TX_ISOLATION may be set by the spec.db.url if it is supported by the driver or as a general setting on the target database DB_USERNAME .spec.db.usernameSecret DB_PASSWORD .spec.db.passwordSecret DB_JNDI No longer applicable 4.4.4. Networking Parameter Migration Red Hat Single Sign-On 7.6 Red Hat build of Keycloak 24.0 HOSTNAME_HTTP .spec.hostname.hostname - with .spec.http.httpEnabled=true. Since the Red Hat build of Keycloak operator will only create a single Ingress/Route, for this to create an http route .spec.http.tlsSecret needs to be left unspecified HOSTNAME_HTTPS .spec.hostname.hostname - with .spec.http.tlsSecret specified. SSO_HOSTNAME .spec.hostname.hostname HTTPS_SECRET .spec.http.tlsSecret - see the other HTTPS parameters below HTTPS_KEYSTORE HTTPS_KEYSTORE_TYPE HTTPS_NAME HTTPS_PASSWORD No longer applicable. The secret referenced by .spec.http.tlsSecret should be of type kubernetes.io/tls with tls.crt and tls.key entries X509_CA_BUNDLE .spec.truststores Note that the Red Hat build of Keycloak Operator does not currently support a way to configure the TLS termination. By default, the passthrough strategy is used. Therefore, the proxy option is not yet exposed as a first-class citizen option field, because it does not matter whether the passthrough or reencrypt strategy is used. However, if you need this option, you can replace the default Ingress Operator certificate and manually configure a Route in order to trust Red Hat build of Keycloak's certificate. The default behavior of the Red Hat build of Keycloak Operator can be then overridden by: additionalOptions: name: proxy value: reencrypt 4.4.5. JGroups Parameter Migration JGROUPS_ENCRYPT_SECRET, JGROUPS_ENCRYPT_KEYSTORE, JGROUPS_ENCRYPT_NAME, JGROUPS_ENCRYPT_PASSWORD, and JGROUPS_CLUSTER_PASSWORD have no first-class representation in the Keycloak CR. Securing cache communication is still possible using the cache configuration file. Additional resources Configuring distributed cache

Commands:
apiVersion: k8s.keycloak.org/v2alpha1 kind: Keycloak metadata: name: rhbk spec: instances: 1 db: vendor: postgres host: postgres-db usernameSecret: name: keycloak-db-secret key: username passwordSecret: name: keycloak-db-secret key: password http: tlsSecret: sso-x509-https-secret
apiVersion: apps.openshift.io/v1 kind: DeploymentConfig metadata: name: rhsso spec: replicas: 1 template: spec: volumes: - name: sso-x509-https-volume secret: secretName: sso-x509-https-secret defaultMode: 420 containers: volumeMounts: - name: sso-x509-https-volume readOnly: true env: - name: DB_SERVICE_PREFIX_MAPPING value: postgres-db=DB - name: DB_USERNAME value: username - name: DB_PASSWORD value: password
additionalOptions: name: proxy value: reencrypt