Este conteúdo não está disponível no idioma selecionado.

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 relevant templates 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

Prerequisites

  • The previous 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.

Procedure

  1. Install Red Hat build of Keycloak Operator to the namespace.
  2. Create new CRs and related Secrets.

    Manually migrate your template based Red Hat Single Sign-On 7.6 configuration to your new Kecyloak CR. See the following examples for suggested mappings between Template parameters and Keycloak CR fields.

    This example shows the Operator CR fields 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
    Copy to Clipboard Toggle word wrap

    This example shows the DeploymentConfig for a Red Hat Single Sign-On 7.6 Template

    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
    Copy to Clipboard Toggle word wrap

4.4. Keycloak CR field names

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

Expand
Red Hat Single Sign-On 7.6Red Hat build of Keycloak 26.4

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

Defaults to admin, can be configured by .spec.bootstrapAdmin.user.secret

SSO_ADMIN_PASSWORD

Created by the operator during the initial reconciliation, can be configured by .spec.bootstrapAdmin.user.secret

MEMORY_LIMIT

.spec.resources.limits[‘memory’]

SSO_SERVICE_PASSWORD, SSO_SERVICE_USERNAME

.spec.bootstrapAdmin.service.secret

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

Expand
Red Hat Single Sign-On 7.6Red Hat build of Keycloak 26.4

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

Expand
Red Hat Single Sign-On 7.6Red Hat build of Keycloak 26.4

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
Copy to Clipboard Toggle word wrap

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. The default clustering with jdbc-ping encrypts the communication by default.

Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat