{"id":30047625,"url":"https://github.com/tmax-cloud/install-hyperauth","last_synced_at":"2026-03-16T13:03:20.845Z","repository":{"id":47589359,"uuid":"315824046","full_name":"tmax-cloud/install-hyperauth","owner":"tmax-cloud","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-28T07:41:30.000Z","size":536,"stargazers_count":2,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-07T09:57:15.834Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmax-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-25T03:59:56.000Z","updated_at":"2024-08-28T07:41:18.000Z","dependencies_parsed_at":"2023-12-08T03:31:34.565Z","dependency_job_id":"72a9667b-2f7d-4a0e-994f-b637c91bad1b","html_url":"https://github.com/tmax-cloud/install-hyperauth","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tmax-cloud/install-hyperauth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-hyperauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-hyperauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-hyperauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-hyperauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmax-cloud","download_url":"https://codeload.github.com/tmax-cloud/install-hyperauth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Finstall-hyperauth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275690752,"owners_count":25510499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-07T09:56:50.513Z","updated_at":"2025-09-18T00:41:13.245Z","avatar_url":"https://github.com/tmax-cloud.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperAuth 설치 가이드\n## 개요\n* Hyperauth\n    * OIDC 와 SSO 프로토콜을 지원하는 인증서버로써 keycloak 을 바탕으로 여러 기능을 추가함 \n## 구성 요소 및 버전\n* hyperauth\n    * [tmaxcloudck/hyperauth:latest](https://hub.docker.com/layers/tmaxcloudck/hyperauth/latest/images/sha256-b4c423520434c37f4c1166f94de7cfa49be43f51efe9f19da10776375b3fd840?context=explore)\n* postgres\n    * postgres:9.6.2-alpine\n* zookeeper\n    * wurstmeister/zookeeper:3.4.6\n* kafka\n    * wurstmeister/kafka:2.12-2.0.1\n    \n## SPEC (21.01.25)\n### Hyperauth\ncpu : 300m\nmemory: 300Mi\n\n## DB (Postgresql, tibero)\ncpu: 300\nmemory: 300Mi\nStorage: 100Gi\n\n### Kafka X 3\ncpu : 100m\nmemory: 100Mi\nStorage: 5Gi\n\n### Zookeeper\ncpu : 100m\nmemory: 100Mi\nStorage: 5Gi\n\n## Prerequisites\n* Java binary\n* jq binary\n* Storage class\n  * 아래 명령어를 통해 storage class가 설치되어 있는지 확인한다.\n    * `$ kubectl get storageclass`\n  * 만약 아무 storage class가 없다면 아래 링크로 이동하여 rook-ceph 설치한다. \n    * https://github.com/tmax-cloud/hypercloud-install-guide/tree/4.1/rook-ceph\n  * Storage class는 있지만 default로 설정된 것이 없다면 아래 명령어를 실행한다.\n    * ` $ kubectl patch storageclass csi-cephfs-sc -p '{\"metadata\": {\"annotations\":{\"storageclass.kubernetes.io/is-default-class\":\"true\"}}}'`\n  * csi-cephfs-sc는 위 링크로 rook-ceph를 설치했을 때 생성되는 storage class이며 다른 storage class를 default로 사용해도 무관하다.\n\n## 폐쇄망 구축 가이드\n1. **폐쇄망에서 설치하는 경우** 사용하는 image repository에 필요한 이미지를 push한다. \n\n    * 작업 디렉토리 생성 및 환경 설정\n    ```bash\n\t$ mkdir -p ~/hyperauth-install\n\t\n\t# For Hyperauth\n\t$ export HYPERAUTH_HOME=~/hyperauth-install\n\t$ cd ${HYPERAUTH_HOME}\n \t$ export POSTGRES_VERSION=9.6.2-alpine\n\t$ export HYPERAUTH_VERSION=\u003ctag1\u003e\n   \t$ export REGISTRY=\u003cREGISTRY_IP_PORT\u003e\n\t\n\t* \u003ctag1\u003e에는 설치할 hyperauth 버전 명시\n\t\t예시: $ export HYPERAUTH_VERSION=1.1.1.10\n\t* \u003cREGISTRY_IP_PORT\u003e에는 폐쇄망 Docker Registry IP:PORT명시\n\t\t예시: $ export REGISTRY=192.168.6.110:5000\n    ```\n    * 외부 네트워크 통신이 가능한 환경에서 필요한 이미지를 다운받는다.\n    ```bash\n\t# postgres\n\t$ sudo docker pull postgres:${POSTGRES_VERSION}\n\t$ sudo docker save postgres:${POSTGRES_VERSION} \u003e postgres_${POSTGRES_VERSION}.tar\n\n\t# hyperauth\n\t$ sudo docker pull tmaxcloudck/hyperauth:b${HYPERAUTH_VERSION}\n\t$ sudo docker save tmaxcloudck/hyperauth:b${HYPERAUTH_VERSION} \u003e hyperauth_b${HYPERAUTH_VERSION}.tar\n    ```\n  \n2. 위의 과정에서 생성한 tar 파일들을 `폐쇄망 환경으로 이동`시킨 뒤 사용하려는 registry에 이미지를 push한다.\n\t\n    * 이미지 load 및 push\n    ```bash\n    # Load Images\n\t$ sudo docker load \u003c postgres_${POSTGRES_VERSION}.tar\n\t$ sudo docker load \u003c hyperauth_b${HYPERAUTH_VERSION}.tar\n\n    # Change Image's Tag For Private Registry\n\t$ sudo docker tag postgres:${POSTGRES_VERSION} ${REGISTRY}/postgres:${POSTGRES_VERSION}\n\t$ sudo docker tag tmaxcloudck/hyperauth:b${HYPERAUTH_VERSION} ${REGISTRY}/hyperauth:b${HYPERAUTH_VERSION}\n    \n    # Push Images\n\t$ sudo docker push ${REGISTRY}/postgres:${POSTGRES_VERSION}\n\t$ sudo docker push ${REGISTRY}/hyperauth:b${HYPERAUTH_VERSION}\n    ```\n\n## 설치 가이드\n1. [초기화 작업](#step-1-%EC%B4%88%EA%B8%B0%ED%99%94-%EC%9E%91%EC%97%85)\n2. [SSL 인증서 생성](#step-2-ssl-%EC%9D%B8%EC%A6%9D%EC%84%9C-%EC%83%9D%EC%84%B1)\n3. [HyperAuth Deployment 생성](#step-3-hyperauth-deployment-%EB%B0%B0%ED%8F%AC)\n4. [Kafka Topic Server 설치](#step-4-kafka-topic-server-%EC%84%A4%EC%B9%98)\n5. [Kubernetes OIDC 연동](#step-5-kubernetes-oidc-%EC%97%B0%EB%8F%99)\n\n추가1. [External-OIDC-Provider 연동]\n\n## Step 1. 초기화 작업 및 yaml 수정\n* 목적 : `HyperAuth 구축을 위한 초기화 작업, Secret생성 및 DB 구축, Yaml 버전 수정`\n* 아래의 command를 수정하여 사용하고자 하는 image 버전 정보를 수정한다.\n```bash\n    $ export POSTGRES_VERSION=9.6.2-alpine\n    $ sed -i 's/POSTGRES_VERSION/'${POSTGRES_VERSION}'/g' 1.initialization.yaml\n    $ export HYPERAUTH_VERSION=b1.1.1.10\n    $ sed -i 's/HYPERAUTH_VERSION/'${HYPERAUTH_VERSION}'/g' 2.hyperauth_deployment.yaml\n ```\n* 생성 순서 :\n\t* kakfa namespace에 strimzi-cluster-operator가 깔려있지 않으면, [strimzi-cluster-operator.yaml](manifest/strimzi-cluster-operator.yaml) 실행 `ex) kubectl apply -f strimzi-cluster-operator.yaml`) \n\t* [1.initialization.yaml](manifest/1.initialization.yaml) 실행 `ex) kubectl apply -f 1.initialization.yaml`)\n* 비고 : 아래 명령어 수행 후, Postgre Admin 접속 확인\n```bash\n    $ kubectl exec -it $(kubectl get pods -n hyperauth | grep postgre | cut -d ' ' -f1) -n hyperauth -- bash\n    $ psql -U keycloak keycloak\n ```\n \n## Step 2. SSL 인증서 생성\n* 목적 : `HTTPS 인증을 위한 인증서, kafka와의 통신을 위한 keystore, truststore를 생성하고 secret으로 변환`\n* 생성 순서 : \n\t* cert-manager가 설치되어 있고, tmaxcloud-issuer (ClusterIssuer) 가 생성되어 있다고 가정한다. \n\t\t* cert-manager 설치는 https://cert-manager.io/docs/installation  \t\n\t\t* 생성이 안되어 있는 경우, [tmaxcloud-issuer.yaml](manifest/tmaxcloud-issuer.yaml) 실행 `ex) kubectl apply -f tmaxcloud-issuer.yaml`) \n\t* [hyperauth_certs.yaml](manifest/hyperauth_certs.yaml) 의 변수를 상황에 맞게 치환한다. 안쓰는 변수 부분은 지워준다.\n\t\t* Hyperauth\n\t\t\t* Hyperauth를 IP로 노출하는 경우, {HYPERAUTH_EXTERNAL_IP} 세팅, dnsName 부분 전체 삭제\n\t\t\t* Hyperauth를 DNS로 노출하는 경우, {HYPERAUTH_EXTERNAL_DNS} 세팅, ipAddresses 부분 전체 삭제\n\t*  [hyperauth_certs.yaml](manifest/hyperauth_certs.yaml) 실행 `ex) kubectl apply -f hyperauth_certs.yaml`)\n\t*  Hyperauth Namespace에 hyperauth-https-secret, hyperauth-kafka-jks, kafka-jks Secret이 생성된걸 확인한다.\n```bash\n    $ kubectl get secrets -n hyperauth\n ``` \t \t  \t\t \t\n \t* hyperauth-https-secret으로 부터 root-ca, hyperauth 인증서를 추출해서 kubernetes pki 에 위치한다.\n```bash\n    $ kubectl get secret hyperauth-https-secret -n hyperauth -o jsonpath=\"{['data']['tls\\.crt']}\" | base64 -d \u003e ./hyperauth.crt\n    $ kubectl get secret hyperauth-https-secret -n hyperauth -o jsonpath=\"{['data']['ca\\.crt']}\" | base64 -d \u003e ./hypercloud-root-ca.crt\n    $ cp ./hyperauth.crt /etc/kubernetes/pki/hyperauth.crt\n    $ cp ./hypercloud-root-ca.crt /etc/kubernetes/pki/hypercloud-root-ca.crt\n ``` \n* 비고 : \n    * Kubernetes Master가 다중화 된 경우, hypercloud-root-ca.crt, hyperauth.crt를 각 Master 노드들의 /etc/kubernetes/pki/hypercloud-root-ca.crt, /etc/kubernetes/pki/hyperauth.crt 로 cp\n\n## Step 3. HyperAuth Deployment 배포\n* 목적 : `HyperAuth 설치`\n* 생성 순서 :\n    * [2.hyperauth_deployment.yaml](manifest/2.hyperauth_deployment.yaml) 실행 `ex) kubectl apply -f 2.hyperauth_deployment.yaml`\n    * HyperAuth Admin Console에 접속 확인\n        * `kubectl get svc hyperauth -n hyperauth` 명령어로 IP 확인\n        * 계정 : admin/admin\n* 비고 :\n    * K8s admin 기본 계정 정보 : hc-admin@tmax.co.kr/Tmaxadmin1!\n    * HyperAuth User 메뉴에서 비밀번호는 변경 가능, ID를 위해서는 clusterrole도 변경 필요\n    \n## Step 4. Kafka Topic Server 설치\n* 목적 : `Hyperauth의 Event를 Subscribe 할수 있는 kafka server 설치`\n* 생성 순서 :\n \t* [3.kafka_deployment.yaml](manifest/3.kafka_deployment.yaml) 실행 `ex) kubectl apply -f 3.kafka_deployment.yaml`\n* 비고 : \n\t* hyperauth 이미지 tmaxcloudck/hyperauth:b1.0.15.31 이후부터 설치 적용할 것!\n\t* [kafka_client.yaml](manifest/3.kafka_client.yaml) 로 pub/sub테스트 가능\n\t\t*  kafka_client pod에 접속 후\n\t\t\t* Producer : \n\t\t\t```bash\n\t\t\t\texport PASSWORD=tmax@23\n\t\t\t\texport KAFKA_OPTS=\" \\\n\t\t\t\t  -Djavax.net.ssl.trustStore=/opt/kafka/certificates/truststore.jks \\\n\t\t\t\t  -Djavax.net.ssl.trustStorePassword=$PASSWORD \\\n\t\t\t\t  -Djavax.net.ssl.trustStoreType=PKCS12\"\n\t\t\t  \t/opt/kafka/bin/kafka-console-producer.sh --broker-list \\\n\t\t\t\t  kafka-kafka-bootstrap.hyperauth:9092 --topic tmax\\\n\t\t\t\t  --producer-property 'security.protocol=SSL'\n\t\t\t```\n\t\t\t* Consumer :\n\t\t\t```bash\n\t\t\t\texport PASSWORD=tmax@23\n\t\t\t\texport KAFKA_OPTS=\" \\\n\t\t\t\t  -Djavax.net.ssl.trustStore=/opt/kafka/certificates/truststore.jks \\\n\t\t\t\t  -Djavax.net.ssl.trustStorePassword=$PASSWORD \\\n\t\t\t\t  -Djavax.net.ssl.trustStoreType=PKCS12\"\n\t\t\t\t/opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server \\\n\t\t\t\t  kafka-kafka-bootstrap.hyperauth:9092 --topic tmax\\\n\t\t\t\t  --consumer-property 'security.protocol=SSL' \\\n\t\t\t\t  --group consumer1\n\t\t\t```\n \n    \n## Step 5. Kubernetes OIDC 연동\n* 목적 : `Kubernetes의 RBAC 시스템과 HyperAuth 인증 연동`\n* 생성 순서 :\n\t* Kubernetes Cluster Master Node에 접속\n\t* {HYPERAUTH_SERVICE_IP} = $(kubectl describe service hyperauth -n hyperauth | grep 'LoadBalancer Ingress' | cut -d ' ' -f7)\n\t* `/etc/kubernetes/manifests/kube-apiserver.yaml` 의 spec.containers[0].command[] 절에 아래 command를 추가\n    \n    ```yaml\n    --oidc-issuer-url=https://{HYPERAUTH_SERVICE_IP}/auth/realms/tmax\n    --oidc-client-id=hypercloud5\n    --oidc-username-claim=preferred_username\n    --oidc-username-prefix=-\n    --oidc-groups-claim=group\n    --oidc-ca-file=/etc/kubernetes/pki/hyperauth.crt\n    ```\n    \n* 비고 :\n    * 자동으로 kube-apiserver 가 재기동 됨\n\n## Step 6. Prometheus 연동 (Optional)\n* 목적 : `Prometheus 모니터링 시스템과 HyperAuth 이벤트 metrics 연동`\n* 필수 요건 \n    * Prometheus 설치 : https://github.com/tmax-cloud/install-prometheus 참조\n    * Admin Console (tmax realm) - Events - Config - Events Config : prometheus-metric-listener 추가\n    * [1.initialization.yaml](manifest/1.initialization.yaml)를 참고하여 passwords Secret에 HYPERAUTH_ADMIN을 추가한다. (hyperauth master realm admin의 아이디를 base64 encoding 하여 생성)\n\n* 생성 순서 :\n    * ServiceMonitor 생성\n    * [4.hyperauth_service_pod_monitor.yaml](manifest/4.hyperauth_service_pod_monitor.yaml) 실행 `ex) kubectl apply -f 4.hyperauth_service_pod_monitor.yaml`\n    \n* 비고 :\n    * 자동으로 Prometheus가 수집을 시작함\n    * grafana dashboard import\n        * grafana - import - https://github.com/tmax-cloud/install-hyperauth/blob/main/manifest/hyperauth_grafana_dashboard.json 내용 붙여넣기\n        * grafana - import - https://github.com/tmax-cloud/install-hyperauth/blob/main/manifest/kafka_grafana_dashboard.json 내용 붙여넣기\n        * grafana - import - https://github.com/tmax-cloud/install-hyperauth/blob/main/manifest/kafka_exporter_grafana_dashboard.json 내용 붙여넣기\n        * grafana - import - https://github.com/tmax-cloud/install-hyperauth/blob/main/manifest/zookeeper_grafana_dashboard.json 내용 붙여넣기\n\n## 추가. External-OIDC-Provider 연동\n* 목적 : Initech의 SSO시스템을 External-OIDC-Provider를 통해서 IDP로 사용\n* 생성 순서\n    * External-OIDC-Provider 생성 : [External-OIDC_Provider 설치가이드](https://github.com/tmax-cloud/external-oidc-provider)\n    * [2.hyperauth_deployment.yaml](manifest/2.hyperauth_deployment.yaml) 수정  \n      1. ``` #Enable ~ if use External-oidc-provider ``` 로 주석 처리된 yaml 필드를 모두 주석 해제  \n      2. External-OIDC-Provider의 도메인 (SERVER_URL 변수)을 아래 ENV로 등록\n         ```yaml\n          - name : EXTERNAL_OIDC_PROVIDER_AUTH_URL  \n            value : https:// {external-oidc-provider.SERVER_URL} /externalauth  \n          - name : EXTERNAL_OIDC_PROVIDER_TOKEN_URL  \n            value : https:// {external-oidc-provider.SERVER_URL} /token  \n          - name : EXTERNAL_OIDC_PROVIDER_PROFILE_URL  \n            value : https:// {external-oidc-provider.SERVER_URL} /profile\n         ```  \n      3. 이후 본 설치가이드를 1. [초기화 작업](#step-1-%EC%B4%88%EA%B8%B0%ED%99%94-%EC%9E%91%EC%97%85) 부터 진행 \n      \n## 참고자료 ( Ingress를 사용해서 hyperauth를 노출하려고 하는 경우 )\n* hyperauth_traefik_ingress.yaml 에서 host 및 hosts를 환경에 맞는 dns로 수정하고 apply한다.\n* 모든 마스터 노드에 관해서 self-signed 인증서의 경우, os의 ca store에 등록하는 과정을 거쳐야 k8s가 공인 인증서로 써 신뢰한다. \n    * hypercloud-root-ca.crt, hyperauth.crt를 /etc/pki/ca-trust/source/anchors/ 밑에 복사한다. (centOS 기준)\n    * update-ca-trust  \t\n    \n\n## 삭제 가이드\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmax-cloud%2Finstall-hyperauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmax-cloud%2Finstall-hyperauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmax-cloud%2Finstall-hyperauth/lists"}