3장. Red Hat Single Sign-On 서버 업그레이드
Red Hat Single Sign-On 서버의 업그레이드 또는 마이그레이션 프로세스는 이전 버전의 소프트웨어에 따라 다릅니다.
- 예를 들어 7.5.x에서 7.6으로 구성된 새로운 마이너 릴리스로 업그레이드하는 경우 마이너 업그레이드 단계를 따르십시오.
- Keycloak 18.0.0에서 마이그레이션하는 경우 마이너 업그레이드의 단계를 따르십시오.
- 예를 들어 7.5.2에서 7.5.3으로 새로운 마이크로 릴리스로 업그레이드하는 경우 Micro Upgrades 의 단계를 따르십시오.
3.1. 마이너 업그레이드 수행
3.1.1. 업그레이드 준비
업그레이드하기 전에 업그레이드 단계를 수행해야 하는 순서를 알고 있어야 합니다. 특히 어댑터를 업그레이드하기 전에 Red Hat Single Sign-On 서버를 업그레이드해야 합니다.
Red Hat Single Sign-On의 마이너 업그레이드에서는 모든 사용자 세션이 손실됩니다. 업그레이드 후에는 모든 사용자가 다시 로그인해야 합니다.
절차
- 이전 설치(구성, 주제, 등)를 백업합니다.
- 데이터베이스 관련 문서의 지침을 사용하여 데이터베이스를 백업합니다.
Red Hat Single Sign-On 서버 업그레이드.
업그레이드 후 데이터베이스는 더 이상 이전 서버와 호환되지 않습니다.
- 업그레이드를 복원해야 하는 경우 먼저 이전 설치를 복원한 다음 백업 사본에서 데이터베이스를 복원합니다.
- 어댑터를 업그레이드합니다.
3.1.2. Red Hat Single Sign-On 서버 업그레이드
서버 업그레이드가 성공했는지 확인하려면 다음 지침을 따르십시오.
- 프로덕션 환경 외 환경에서 업그레이드를 테스트하여 프로덕션의 설치 문제를 방지합니다.
- 어댑터를 업그레이드하기 전에 Red Hat Single Sign-On 서버를 업그레이드하십시오. 또한 어댑터를 업그레이드하기 전에 업그레이드된 서버가 프로덕션에서 작동하는지 확인하십시오.
설치와 관련된 수동 변경으로 인해 이 업그레이드 절차를 수정해야 할 수 있습니다. 업그레이드에 영향을 줄 수 있는 수동 변경 사항에 대한 자세한 내용은 릴리스별 변경 사항을 참조하십시오.
ZIP 파일 또는 설치에 사용한 방법에 따라 RPM 에서 서버를 업그레이드합니다.
3.1.2.1. ZIP 파일에서 서버 업그레이드
사전 요구 사항
- 열려 있는 모든 트랜잭션을 처리하고 data/tx-object-store/ 트랜잭션 디렉토리를 삭제합니다.
절차
- 새 서버 아카이브를 다운로드합니다.
- 다운로드한 아카이브를 원하는 위치로 이동합니다.
- 아카이브를 추출합니다. 이 단계에서는 최신 Red Hat Single Sign-On 릴리스의 깔끔한 인스턴스를 설치합니다.
독립 실행형 설치의 경우 이전 설치의
RHSSO_HOME/standalone/디렉터리를 새 설치의 디렉터리에 복사합니다.도메인 설치의 경우 이전 설치의
RHSSO_HOME/domain/디렉터리를 새 설치의 디렉터리에 복사합니다.도메인 설치의 경우 빈 디렉터리
RHSSO_HOME/domain/deployments를 생성합니다.참고: bin 디렉토리의 파일은 이전 버전의 파일에서 덮어쓰지 않아야 합니다. 변경 사항은 수동으로 수행해야 합니다.
- modules 디렉터리에 추가된 모든 사용자 지정 모듈을 복사합니다.
- 서버 업그레이드 스크립트 실행이라는 섹션을 계속합니다.
3.1.2.2. RPM에서 서버 업그레이드
사전 요구 사항
- 열려 있는 모든 트랜잭션을 처리하고 /var/opt/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ 트랜잭션 디렉토리를 삭제합니다.
절차
Red Hat Single Sign-On이 포함된 적절한 리포지토리에 가입하십시오.
Red Hat Enterprise Linux 7의 경우:
subscription-manager repos --enable=rh-sso-7.6-for-rhel-7-x86_64-rpms
Red Hat Enterprise Linux 8의 경우:
subscription-manager repos --enable=rh-sso-7.6-for-rhel-8-x86_64-rpms
Red Hat Single Sign-On의 이전 제품 리포지터리를 비활성화합니다.
subscription-manager repos --disable=rh-sso-7.5-for-rhel-8-x86_64-rpms
리포지토리 목록을 확인합니다.
dnf repolist
Updating Subscription Management repositories. repo id repo name rh-sso-7.6-for-rhel-8-x86_64-rpms Single Sign-On 7.6 for RHEL 8 x86_64 (RPMs) rhel-8-for-x86_64-appstream-rpms Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs) rhel-8-for-x86_64-baseos-rpms Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)
- 수정된 구성 파일 및 사용자 지정 모듈을 백업합니다.
dnf 업그레이드를사용하여 새로운 Red Hat Single Sign-On 버전으로 업그레이드하십시오.RPM 업그레이드 프로세스에서는 수정된 구성 파일을 대체하지 않습니다. 대신 이 프로세스에서는 새로운 Red Hat Single Sign-On 버전의 기본 구성에 대해 .rpmnew 파일을 생성합니다.
- 새 하위 시스템과 같은 새 릴리스의 새로운 기능을 활성화하려면 각 .rpmnew 파일을 기존 구성 파일에 수동으로 병합합니다.
- modules 디렉터리에 추가된 모든 사용자 지정 모듈을 복사합니다.
서버 업그레이드 스크립트 실행이라는 섹션을 계속합니다.
참고Red Hat Single Sign-On RPM 서버 배포 사용
RHSSO_HOME=/opt/rh/rh-sso7/root/usr/share/keycloak아래 마이그레이션 스크립트를 호출할 때 사용합니다.
3.1.3. 서버 업그레이드 스크립트 실행
이전 설치에 따라 상황에 적용되는 적절한 업그레이드 스크립트를 실행합니다.
3.1.3.1. 독립 실행형 모드 업그레이드 스크립트 실행
절차
- 기본 구성 파일과 다른 구성 파일을 사용하는 경우 마이그레이션 스크립트를 편집하여 새 파일 이름을 지정합니다.
- 서버를 중지합니다.
업그레이드 스크립트를 실행합니다.
bin/jboss-cli.sh --file=bin/migrate-standalone.cli
3.1.3.2. 독립 실행형-High Availability Mode 업그레이드 스크립트 실행
독립 실행형 HA(고가용성) 모드의 경우 모든 인스턴스를 동시에 업그레이드해야 합니다.
절차
- 기본 구성 파일과 다른 구성 파일을 사용하는 경우 마이그레이션 스크립트를 편집하여 새 파일 이름을 지정합니다.
- 서버를 중지합니다.
업그레이드 스크립트를 실행합니다.
bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
3.1.3.3. 도메인 모드 업그레이드 스크립트 실행
도메인 모드의 경우 모든 인스턴스를 동시에 업그레이드해야 합니다.
절차
- 프로필 이름을 변경한 경우 스크립트 시작 가까운 변수를 변경하기 위해 업그레이드 스크립트를 편집해야 합니다.
- 도메인 스크립트를 편집하여 keycloak-server.json 파일의 위치를 포함합니다.
- 서버를 중지합니다.
도메인 컨트롤러에서 업그레이드 스크립트 실행
bin/jboss-cli.sh --file=bin/migrate-domain.cli
3.1.3.4. 도메인 클러스터 모드 업그레이드 스크립트 실행
도메인 클러스터 모드의 경우 모든 인스턴스를 동시에 업그레이드해야 합니다.
절차
- 프로필 이름을 변경한 경우 스크립트 시작 가까운 변수를 변경하기 위해 업그레이드 스크립트를 편집해야 합니다.
- domain-clustered 스크립트를 편집하여 keycloak-server.json 파일의 위치를 포함합니다.
- 서버를 중지합니다.
도메인 컨트롤러에서만 업그레이드 스크립트를 실행합니다.
bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli
3.1.4. 데이터베이스 마이그레이션
Red Hat Single Sign-On은 데이터베이스 스키마를 자동으로 마이그레이션하거나 수동으로 수행하도록 선택할 수 있습니다. 기본적으로 새 설치를 처음 시작하면 데이터베이스가 자동으로 마이그레이션됩니다.
3.1.4.1. 자동 관계형 데이터베이스 마이그레이션
데이터베이스 스키마의 자동 업그레이드를 활성화하려면 기본 connectionsJpa 공급자에 대해 migrationStrategy 속성 값을 업데이트하도록 설정합니다.
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
...
<property name="migrationStrategy" value="update"/>
</properties>
</provider>
</spi>또는 다음 CLI 명령을 실행합니다.
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
이 설정으로 서버를 시작하면 데이터베이스 스키마가 새 버전에서 변경된 경우 데이터베이스가 자동으로 마이그레이션됩니다.
수백만 개의 레코드가 있는 대규모 테이블에 인덱스를 생성하면 쉽게 시간이 오래 걸릴 수 있으며 업그레이드에 심각한 서비스가 중단될 수 있습니다. 이러한 경우 자동화된 인덱스 생성을 위한 임계값(기록 수)을 추가했습니다. 기본적으로 이 임계값은 300000 개의 레코드입니다. 레코드 수가 임계값보다 크면 인덱스가 자동으로 생성되지 않으며 나중에 수동으로 적용할 수 있는 SQL 명령을 비롯한 서버 로그에 경고 메시지가 표시됩니다.
임계값을 변경하려면 기본 connectionsLiquibase 공급자의 indexCreationThreshold 속성 값을 설정합니다.
<spi name="connectionsLiquibase">
<provider name="default" enabled="true">
<properties>
<property name="indexCreationThreshold" value="300000"/>
</properties>
</provider>
</spi>또는 다음 CLI 명령을 실행합니다.
/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)3.1.4.2. 수동 관계형 데이터베이스 마이그레이션
데이터베이스 스키마를 수동으로 업그레이드하려면 기본 connectionsJpa 공급자에 대해 migrationStrategy 속성 값을 manual 로 설정합니다.
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
...
<property name="migrationStrategy" value="manual"/>
</properties>
</provider>
</spi>또는 다음 CLI 명령을 실행합니다.
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)
이 구성으로 서버를 시작하면 데이터베이스를 마이그레이션해야 하는지 확인합니다. 필요한 변경 사항은 데이터베이스에 대해 검토 및 수동으로 실행할 수 있는 SQL 파일에 기록됩니다. 이 파일을 데이터베이스에 적용하는 방법에 대한 자세한 내용은 사용 중인 관계 데이터베이스 설명서를 참조하십시오. 파일에 변경 사항을 작성한 후 서버가 종료됩니다.
3.1.5. meme 마이그레이션
사용자 지정 주제를 생성한 경우 새 서버로 마이그레이션해야 합니다. 내장된 주제의 모든 변경 사항은 사용자 지정 내용에 따라 사용자 지정 항목에 반영해야 할 수 있습니다.
이전 서버 themes 디렉터리의 사용자 지정 주제를 새 서버 디렉터리에 복사해야 합니다. 그런 다음 아래 변경 사항을 검토하고 변경 사항을 사용자 지정 topic에 적용해야 하는지 고려해야 합니다.
themes
요약하면 다음과 같습니다.
- 아래에 나열된 변경된 템플릿을 사용자 지정한 경우 기본 주제의 템플릿을 비교하여 적용해야 하는 변경 사항이 있는지 확인해야 합니다.
- 스타일을 사용자 지정하고 Red Hat Single Sign-On 주제를 확장하는 경우 스타일 변경 사항을 검토해야 합니다. 기본 주제를 확장하는 경우 이 단계를 건너뛸 수 있습니다.
- 사용자 지정 메시지가 있는 경우 키 또는 값을 변경하거나 메시지를 추가해야 할 수 있습니다.
각 단계는 변경 사항 목록 아래에 자세히 설명되어 있습니다.
3.1.5.1. Theme changes RH-SSO 7.3
템플릿
- 계정: account.ftl
- 계정: applications.ftl
- 계정: resource-detail.ftl (new)
- 계정: resources.ftl (new)
- 계정: template.ftl
- 계정: totp.ftl
- email-html: email-test.ftl
- email-html: email-verification-with-code.ftl (new)
- email-html: email-verification.ftl
- email-html: event-login_error.ftl
- Email-html: event-removed_totp.ftl
- Email-html: event-update_password.ftl
- Email-html: event-update_totp.ftl
- email-html: actions.ftl을 실행합니다.
- email-html: identity-provider-link.ftl
- email-html: password-reset.ftl
- email-text: email-verification-with-code.ftl (new)
- email-text: email-verification.ftl
- email-text: execute actionsions.ftl
- email-text: identity-provider-link.ftl
- email-text: password-reset.ftl
- 로그인: cli_splash.ftl (new)
- 로그인: code.ftl
- 로그인: error.ftl
- 로그인: info.ftl
- 로그인: login-config-totp-text.ftl (new)
- Login: login-config-totp.ftl
- Login: login-idp-link-confirm.ftl
- Login: login-idp-link-email.ftl
- 로그인: login-oauth-grant.ftl
- 로그인: login-page-expired.ftl
- Login: login-reset-password.ftl
- Login: login-totp.ftl
- Login: login-update-password.ftl
- 로그인: login-update-profile.ftl
- 로그인: login-verify-email-code-text.ftl (new)
- 로그인: login-verify-email.ftl
- Login: login-x509-info.ftl
- 로그인: login.ftl
- 로그인: register.ftl
- 로그인: template.ftl
- 로그인: terms.ftl
- 환영합니다: index.ftl (new)
메시지
- 계정: messages_en.properties
- admin: admin-ECDHE_en.properties
- 이메일: messages_en.properties
- 로그인: messages_en.properties
style
- login: login-rhsso.css (new)
- 환영합니다: welcome-rhsso.css
3.1.5.2. Theme changes RH-SSO 7.2
템플릿
- 계정: account.ftl
- 계정: applications.ftl
- 계정: federatedIdentity.ftl
- 계정: password.ftl
- 계정: sessions.ftl
- 계정: template.ftl
- 계정: totp.ftl
- 관리자: index.ftl
- 이메일: email-test.ftl (new)
- 이메일: email-verification.ftl
- 이메일: event-login_error.ftl
- 이메일: event-removed_totp.ftl
- Email: event-update_password.ftl
- Email: event-update_totp.ftl
- 이메일: execute Actionsions.ftl
- 이메일: identity-provider-link.ftl
- 이메일: password-reset.ftl
- login: bypass_kerberos.ftl (removed)
- 로그인: error.ftl
- 로그인: info.ftl
- Login: login-config-totp.ftl
- Login: login-idp-link-email.ftl
- 로그인: login-oauth-grant.ftl
- login: login-page-expired.ftl (new)
- Login: login-reset-password.ftl
- Login: login-totp.ftl
- Login: login-update-password.ftl
- 로그인: login-update-profile.ftl
- 로그인: login-verify-email.ftl
- 로그인: login-x509-info.ftl (new)
- 로그인: login.ftl (new)
- 로그인: register.ftl (new)
- 로그인: template.ftl (new)
- 로그인: terms.ftl (new)
메시지
- 계정: messages_en.properties
- admin: admin-ECDHE_en.properties
- admin: messages_en.properties
- 이메일: messages_en.properties
- 로그인: messages_en.properties
style
- 계정: account.css
- 로그인: login.css
3.1.5.3. Theme changes RH-SSO 7.1
템플릿
- 계정: account.ftl
- 계정: federatedIdentity.ftl
- 계정: totp.ftl
- 로그인: info.ftl
- Login: login-config-totp.ftl
- Login: login-reset-password.ftl
- 로그인: login.ftl
메시지
- 계정: editAccountHtmlTtile의 이름이 editAccountHtmlTitle으로 변경됩니다.
- 계정: role_uma_authorization 추가
- loginTotpStep1 값이 변경됨
- 로그인: invalidPasswordGenericMessage 추가
- login: invlidRequesterMessage의 이름이 invalidRequesterMessage로 변경됨
- 로그인: clientDisabledMessage 추가
style
- 계정: account.css
- 로그인: login.css
3.1.5.4. 템플릿 마이그레이션
템플릿을 사용자 지정한 경우 템플릿에 수행된 변경 사항을 주의 깊게 검토하여 이러한 변경 사항을 사용자 지정 템플릿에 적용해야 하는지 결정해야 합니다. 대부분의 경우 사용자 지정 템플릿에 동일한 변경 사항을 적용해야 합니다. 나열된 템플릿을 사용자 정의하지 않은 경우 이 섹션을 생략할 수 있습니다.
diff 도구를 사용하여 템플릿을 비교하여 사용자 지정 템플릿에 필요한 변경 사항을 확인하는 것이 가장 좋습니다. 약간의 변경만 있는 경우 업데이트된 템플릿을 사용자 지정 템플릿과 비교하여 더 쉽게 수행할 수 있습니다. 그러나 많은 변경을 수행한 경우 새 템플릿을 사용자 지정된 이전 템플릿과 비교하기가 더 쉬워질 수 있습니다. 이 경우 필요한 변경 사항이 표시됩니다.
다음 스크린샷은 info.ftl 템플릿을 로그인 주제와 예제 사용자 지정 주제의 예를 비교합니다.
사용자 정의 로그인 topic 템플릿 예와 함께 업데이트된 버전의 로그인 topic 템플릿 비교
이 비교에서 첫 번째 변경 내용(Hello world!!!)이 사용자 지정인지 확인하는 것은 쉽지만 두 번째 변경 사항(pageRedirectUri)은 기본 조정에 대한 변경 사항입니다. 두 번째 변경 사항을 사용자 지정 템플릿에 복사하여 사용자 지정 템플릿을 성공적으로 업데이트했습니다.
대체 접근 방식의 경우 다음 스크린샷은 이전 설치의 info.ftl 템플릿을 새 설치의 업데이트된 info.ftl 템플릿과 비교합니다.
업데이트된 버전의 로그인 topic 템플릿과 이전 설치의 로그인 장 템플릿 비교
이러한 비교에서 기본 템플릿에서 변경된 내용을 쉽게 식별할 수 있습니다. 그러면 수정된 템플릿에 동일한 변경 작업을 수동으로 수행해야 합니다. 이 접근 방식은 첫 번째 접근 방식만큼 간단하지 않기 때문에 첫 번째 방법이 가능하지 않은 경우에만 이 방법을 사용하십시오.
3.1.5.5. 메시지 마이그레이션
다른 언어에 대한 지원을 추가한 경우 위에 나열된 모든 변경 사항을 적용해야 합니다. 다른 언어에 대한 지원을 추가하지 않은 경우, 아무것도 변경할 필요가 없습니다. 주제에서 영향을 받는 메시지를 변경한 경우에만 변경해야 합니다.
추가된 값의 경우 기본 주제의 메시지 값을 검토하여 해당 메시지를 사용자 지정해야 하는지 확인합니다.
이름이 변경된 키의 경우 사용자 지정 topic의 키 이름을 바꿉니다.
변경된 값의 경우 기본 주제의 값을 확인하여 사용자 지정 topic을 변경해야 하는지 확인합니다.
3.1.5.6. 스타일 마이그레이션
keycloak 또는 rh-sso themes에서 style을 상속하는 경우 기본 제공 주제의 스타일에 대한 변경 사항을 반영하도록 사용자 지정 스타일을 업데이트해야 할 수 있습니다.
diff 도구를 사용하여 이전 서버 설치와 새 서버 설치 간의 스타일 대결 변경 사항을 비교하는 것이 좋습니다.
예를 들어 diff 명령을 사용합니다.
$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \ RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css
변경 사항을 검토하고 사용자 지정 열화에 영향을 미치는지 확인합니다.
