diff --git a/.env.example b/.env.example index 601b695..3595434 100644 --- a/.env.example +++ b/.env.example @@ -1,4 +1,4 @@ -# .env に写して、この機械に合わせて書く。.env はコミットしない。 +# .env にコピーして、この機械に合わせて書き換える。.env はコミットしない。 # データベースのパスワード。空のままでは起動しない。`;` は使えない POSTGRES_PASSWORD= @@ -12,24 +12,24 @@ CARINA_RECORDINGS_DIR= # エンコード済みファイルを書くホスト側のディレクトリ。ライブラリと一緒に増える CARINA_ENCODES_DIR= -# OIDC の client secret を暗号化する鍵を置くホスト側のディレクトリ。データベースとは別に残す +# OIDC の client secret や通知の送り先を暗号化する鍵 (ASP.NET Core Data Protection) と、Web Push の署名に使う鍵を置くホスト側のディレクトリ。データベースとは別にバックアップする CARINA_KEYS_DIR= -# ブラウザからこのサーバに届くアドレス (https://tv.example.com など)。ID プロバイダに登録する redirect URI の元になる +# ブラウザから見たこのサーバのアドレス (https://tv.example.com など)。ID プロバイダに登録する redirect URI の元になる CARINA_PUBLIC_ORIGIN= -# Caddy が開くサイトのアドレス。公開のドメイン (tv.example.com) なら https で開き証明書を取る。LAN だけなら :80 のまま +# Caddy が待ち受けるサイトのアドレス。公開のドメイン (tv.example.com) なら証明書を取得して https で待ち受ける。LAN だけなら :80 のまま PYXIS_SITE_ADDRESS=:80 # ホスト側で開く http と https のポート。80 と 443 がほかに使われているなら別の番号にする PYXIS_HTTP_PORT=80 PYXIS_HTTPS_PORT=443 -# 録画をあとからエンコードするときの変換器。Software、Vaapi、Nvenc のどれか (GPU を渡したとき) +# 録画をあとからエンコードするときのエンコーダー。Software、Vaapi、Nvenc のどれか (Vaapi と Nvenc は GPU を渡したとき) CARINA_ENCODINGS_PREFER=Software -# ライブと録画再生をその場で変換するときの変換器。Software、Vaapi、Nvenc のどれか (GPU を渡したとき) +# ライブと録画再生をリアルタイムでトランスコードするときのエンコーダー。Software、Vaapi、Nvenc のどれか (Vaapi と Nvenc は GPU を渡したとき) CARINA_TRANSCODING_PREFER=Software -# VAAPI で使う GPU の描画ノード +# VAAPI で使う GPU の render ノード CARINA_RENDER_NODE=/dev/dri/renderD128 diff --git a/.yamllint b/.yamllint index 7c2e602..5e7318b 100644 --- a/.yamllint +++ b/.yamllint @@ -7,6 +7,6 @@ rules: truthy: check-keys: false -# Helm のテンプレートは描く前の YAML ではない +# Helm のテンプレートはレンダリングするまで YAML として解釈できない ignore: - charts/pyxis/templates/ diff --git a/Caddyfile b/Caddyfile index 8feb584..92eaf04 100644 --- a/Caddyfile +++ b/Caddyfile @@ -1,9 +1,9 @@ # 同じオリジンで /api/* を app に、それ以外を vela に振り分ける。 -# PYXIS_SITE_ADDRESS に公開のドメインを書くと Caddy が証明書を取って https で開き、:80 なら http で開く。 +# PYXIS_SITE_ADDRESS に公開のドメインを書くと Caddy が証明書を取得して https で待ち受け、:80 なら http で待ち受ける。 # アクセスログは取らない (外部プレイヤーの URL はパスに再生用のトークンを含む)。 {$PYXIS_SITE_ADDRESS} { handle /api/* { - # SSE (/api/events) を溜めない。WebSocket (/api/live/ws) と Range はそのまま通る + # SSE (/api/events) をバッファリングしない。WebSocket (/api/live/ws) と Range はそのまま通る reverse_proxy app:8080 { flush_interval -1 } diff --git a/README.md b/README.md index 4992a26..48bc5aa 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ B-CAS カードを 1 枚しか持っていなくても、別の機械のチュ - B-CAS カードとカードリーダー。ホストで pcscd を動かしておきます - Intel の GPU か NVIDIA の GPU(任意)。NVIDIA は NVIDIA Container Toolkit とドライバ 530.41.03 以上が要ります。H.265 と AV1 のエンコード、ライブと再生の変換に使います -チューナーとカードが無い機械でも、合成チューナーで画面を開くところまでは試せます。 +チューナーとカードが無い機械でも、擬似チューナーで画面を開くところまでは試せます。 ## 動かす diff --git a/charts/pyxis/Chart.yaml b/charts/pyxis/Chart.yaml index ba3eaa1..d45846f 100644 --- a/charts/pyxis/Chart.yaml +++ b/charts/pyxis/Chart.yaml @@ -18,7 +18,7 @@ keywords: - carina - vela annotations: - # この版が固定するイメージの組。compose.yml と values.yaml の image と同じ値にする + # このバージョンで固定するイメージの組み合わせ。compose.yml と values.yaml の image と同じ値にする images/carina-app: ghcr.io/newworldorg/carina:v2.1.0 images/puppis-driver: ghcr.io/newworldorg/puppis:v0.3.0 images/vela: ghcr.io/newworldorg/vela:v1.4.0 diff --git a/charts/pyxis/ci/default-values.yaml b/charts/pyxis/ci/default-values.yaml index d41ddfa..137951c 100644 --- a/charts/pyxis/ci/default-values.yaml +++ b/charts/pyxis/ci/default-values.yaml @@ -1,4 +1,4 @@ -# 既定の形。合成のチューナー、同梱のデータベース、GPU なし、標準の Ingress +# 既定の構成。テスト用の擬似チューナー (fake)、同梱のデータベース、GPU なし、標準の Ingress postgres: auth: password: check diff --git a/charts/pyxis/ci/driver-only-values.yaml b/charts/pyxis/ci/driver-only-values.yaml index 5567806..f043006 100644 --- a/charts/pyxis/ci/driver-only-values.yaml +++ b/charts/pyxis/ci/driver-only-values.yaml @@ -1,4 +1,4 @@ -# driver だけを別の機械に立てる形。ホストのネットワークでカードを貸し、app・画面・DB・前段は作らない +# driver だけを別の機械で動かす構成。ホストのネットワークでカードを貸し、app・Vela・データベース・Ingress は作らない driver: hostNetwork: true config: diff --git a/charts/pyxis/ci/external-db-values.yaml b/charts/pyxis/ci/external-db-values.yaml index aee0ab1..d46e650 100644 --- a/charts/pyxis/ci/external-db-values.yaml +++ b/charts/pyxis/ci/external-db-values.yaml @@ -1,4 +1,4 @@ -# 外のデータベース。同梱の DB を作らず、接続文字列を Secret から読む。GPU は hostPath、サムネイルと字幕は emptyDir +# 外部のデータベースを使う構成。同梱のデータベースを作らず、接続文字列を Secret から読む。GPU は hostPath、サムネイルと字幕は emptyDir postgres: enabled: false externalDatabase: diff --git a/charts/pyxis/ci/ingressroute-gpu-values.yaml b/charts/pyxis/ci/ingressroute-gpu-values.yaml index 2c2f01d..7e92e74 100644 --- a/charts/pyxis/ci/ingressroute-gpu-values.yaml +++ b/charts/pyxis/ci/ingressroute-gpu-values.yaml @@ -1,4 +1,4 @@ -# Traefik の IngressRoute と Intel の device plugin。DVB のチューナーと pcscd を渡し、置き場は hostPath +# Traefik の IngressRoute と Intel の device plugin。DVB のチューナーと pcscd を渡し、ボリュームはすべて hostPath nodeSelector: kubernetes.io/hostname: node-1 driver: diff --git a/charts/pyxis/ci/kind-sizes.yaml b/charts/pyxis/ci/kind-sizes.yaml index af963fc..27e4a70 100644 --- a/charts/pyxis/ci/kind-sizes.yaml +++ b/charts/pyxis/ci/kind-sizes.yaml @@ -1,4 +1,4 @@ -# kind での起動の試験で default-values.yaml に重ねる値。名前を *-values.yaml にしないのは、chart の job が単体で lint と描画をする組と区別するため。置き場を小さくし、そのほかは既定のまま +# kind での起動テストで default-values.yaml に重ねる値。ファイル名を *-values.yaml にしないのは、chart の job が単体で lint とレンダリングをする values ファイルと区別するため。ボリュームのサイズを小さくし、そのほかは既定のまま persistence: recordings: size: 1Gi diff --git a/charts/pyxis/ci/nvidia-values.yaml b/charts/pyxis/ci/nvidia-values.yaml index 5278380..4b25d03 100644 --- a/charts/pyxis/ci/nvidia-values.yaml +++ b/charts/pyxis/ci/nvidia-values.yaml @@ -1,4 +1,4 @@ -# NVIDIA の GPU を RuntimeClass と device plugin で渡し、エンコードを Nvenc にする +# NVIDIA の GPU を RuntimeClass と device plugin で渡し、エンコーダーを Nvenc にする app: encodingsPrefer: Nvenc transcodingPrefer: Nvenc diff --git a/charts/pyxis/templates/NOTES.txt b/charts/pyxis/templates/NOTES.txt index b23dc48..935ad65 100644 --- a/charts/pyxis/templates/NOTES.txt +++ b/charts/pyxis/templates/NOTES.txt @@ -1,22 +1,22 @@ -{{ .Release.Name }} を名前空間 {{ .Release.Namespace }} に入れた。 +{{ .Release.Name }} を名前空間 {{ .Release.Namespace }} にインストールした。 {{- if .Values.driver.enabled }} -driver は特権で動く。名前空間の Pod Security が privileged でないと driver は上がらない。 +driver は特権コンテナで動く。名前空間の Pod Security が privileged でないと driver の Pod は起動しない。 kubectl label namespace {{ .Release.Namespace }} pod-security.kubernetes.io/enforce=privileged {{- end }} {{- if and .Values.driver.enabled .Values.app.enabled (not .Values.nodeSelector) (not .Values.driver.nodeSelector) (not .Values.app.nodeSelector) }} -nodeSelector が無い。ノードが複数のクラスタでは driver と app が別のノードに載り、ソケットでつながらない。 -値の nodeSelector に、チューナーのあるノードを書く。 +nodeSelector が指定されていない。ノードが複数のクラスタでは、driver と app が別のノードにスケジュールされるとソケットで接続できない。 +values の nodeSelector に、チューナーのあるノードを指定する。 {{- end }} {{- if .Values.app.enabled }} -最初の起動で app がローカルアカウントを作り、ユーザー名とパスワードをログに 1 度だけ書く。 +初回の起動で app がローカルアカウントを作り、ユーザー名とパスワードをログに 1 回だけ出力する。 kubectl -n {{ .Release.Namespace }} logs deploy/{{ include "pyxis.partName" (dict "root" . "part" "app") }} -c app | grep 'Sign in as' {{- end }} {{- if and .Values.vela.enabled (ne .Values.route.kind "none") }} -ブラウザで {{ if .Values.route.host }}https://{{ .Values.route.host }}/{{ else }}前段のアドレス{{ end }} を開く。 +ブラウザで {{ if .Values.route.host }}https://{{ .Values.route.host }}/{{ else }}Ingress コントローラのアドレス{{ end }} を開く。 {{- end }} diff --git a/charts/pyxis/templates/_helpers.tpl b/charts/pyxis/templates/_helpers.tpl index 29874f5..f0af756 100644 --- a/charts/pyxis/templates/_helpers.tpl +++ b/charts/pyxis/templates/_helpers.tpl @@ -1,12 +1,12 @@ {{/* -部品の名前。リリース名に部品の名前をつなぐ (carina-driver、carina-app、carina-db、carina-vela) +コンポーネントのリソース名。リリース名にコンポーネントの名前をつなぐ (carina-driver、carina-app、carina-db、carina-vela) */}} {{- define "pyxis.partName" -}} {{- printf "%s-%s" .root.Release.Name .part | trunc 63 | trimSuffix "-" -}} {{- end -}} {{/* -資源の metadata に付けるラベル。チャートの版はここにだけ入れ、Pod のテンプレートには入れない +リソースの metadata に付けるラベル。チャートのバージョンはここにだけ入れ、Pod のテンプレートには入れない */}} {{- define "pyxis.labels" -}} helm.sh/chart: {{ printf "%s-%s" .root.Chart.Name .root.Chart.Version | replace "+" "_" }} @@ -25,7 +25,7 @@ app.kubernetes.io/component: {{ .part }} {{- end -}} {{/* -部品の nodeSelector。部品のものがあればそれを、無ければ共通のものを使う +コンポーネントの nodeSelector。コンポーネントに指定があればそれを、無ければ共通のものを使う */}} {{- define "pyxis.nodeSelector" -}} {{- $selector := .own | default .root.Values.nodeSelector -}} @@ -35,9 +35,6 @@ nodeSelector: {{- end }} {{- end -}} -{{/* -Pod の imagePullSecrets -*/}} {{- define "pyxis.imagePullSecrets" -}} {{- with .Values.imagePullSecrets }} imagePullSecrets: @@ -48,7 +45,7 @@ imagePullSecrets: {{- end -}} {{/* -置き場の volume の中身。type が pvc、existingClaim、hostPath、emptyDir のどれかで形が変わる +persistence の各ボリュームの volume ソース。type が pvc、existingClaim、hostPath、emptyDir のどれかで内容が変わる */}} {{- define "pyxis.volumeSource" -}} {{- $spec := index .root.Values.persistence .name -}} @@ -77,7 +74,7 @@ emptyDir: {} {{- end -}} {{/* -app と migrate に渡す接続文字列の環境変数。同梱のときは Service 名とパスワードから組み、外のときは Secret から読む +app と migrate に渡す接続文字列の環境変数。同梱のデータベースなら Service 名とパスワードから組み立て、外部のデータベースなら Secret から読む */}} {{- define "pyxis.connectionStringEnv" -}} {{- if .Values.postgres.enabled }} diff --git a/charts/pyxis/templates/app-deployment.yaml b/charts/pyxis/templates/app-deployment.yaml index d99354f..eefd5f7 100644 --- a/charts/pyxis/templates/app-deployment.yaml +++ b/charts/pyxis/templates/app-deployment.yaml @@ -9,7 +9,7 @@ metadata: labels: {{- include "pyxis.labels" (dict "root" . "part" "app") | nindent 4 }} spec: - # 予約の確認やエンコードの列をプロセスの中に持つので 1 つだけ。古い app が止まってから migrate を当てる + # 予約の確認やエンコードのキューをプロセスの中に持つのでレプリカは 1 つだけ。古い app が停止してからマイグレーションを実行する replicas: 1 strategy: type: Recreate @@ -24,7 +24,7 @@ spec: {{- with include "pyxis.imagePullSecrets" . }}{{ . | trim | nindent 6 }}{{- end }} {{- with include "pyxis.nodeSelector" (dict "root" . "own" $app.nodeSelector) }}{{ . | trim | nindent 6 }}{{- end }} {{- if eq $app.gpu.mode "nvidia" }} - # NVIDIA Container Toolkit の runtime が、ドライバのライブラリと装置をコンテナに差し込む + # NVIDIA Container Toolkit のランタイムが、ドライバのライブラリとデバイスをコンテナにマウントする runtimeClassName: {{ $app.gpu.runtimeClassName }} {{- end }} securityContext: @@ -35,7 +35,7 @@ spec: {{- end }} initContainers: {{- if $app.dataProtection.seedSecret }} - # client secret を封じる鍵の種を、置き場に無いときだけ写す。あとから増えた鍵には触らない + # seedSecret の Data Protection の鍵ファイルを、keys のボリュームに同じ名前のファイルが無いときだけコピーする。あとから増えた鍵には触らない - name: seed-keys image: {{ $image | quote }} imagePullPolicy: {{ $app.image.pullPolicy }} @@ -71,14 +71,14 @@ spec: image: {{ $image | quote }} imagePullPolicy: {{ $app.image.pullPolicy }} {{- if eq $app.gpu.mode "devicePlugin" }} - # device plugin が作る装置は root:root 0660 で app が開けない。グループを app のものに替えてから entrypoint に渡す + # device plugin が作るデバイスノードは root:root 0660 で app が開けない。グループを app の gid に変えてから entrypoint を実行する command: - bash - -c - chgrp {{ $gid }} /dev/dri/* && exec /usr/local/bin/carina app {{- end }} {{- if eq $app.gpu.mode "hostPath" }} - # hostPath で渡した装置は device cgroup が開かせないので、特権にする + # hostPath でマウントしたデバイスは device cgroup がアクセスを許可しないので、特権コンテナにする securityContext: privileged: true {{- end }} diff --git a/charts/pyxis/templates/db-secret.yaml b/charts/pyxis/templates/db-secret.yaml index 9f6a933..ababea9 100644 --- a/charts/pyxis/templates/db-secret.yaml +++ b/charts/pyxis/templates/db-secret.yaml @@ -1,6 +1,6 @@ {{- if and .Values.postgres.enabled (not .Values.postgres.auth.existingSecret) }} {{- if not .Values.postgres.auth.password }} -{{- fail "postgres.auth.existingSecret か postgres.auth.password のどちらかにデータベースのパスワードを書く" }} +{{- fail "postgres.auth.existingSecret にパスワードを持つ Secret の名前を書くか、postgres.auth.password にデータベースのパスワードを書く" }} {{- end }} apiVersion: v1 kind: Secret diff --git a/charts/pyxis/templates/driver-deployment.yaml b/charts/pyxis/templates/driver-deployment.yaml index e28f20a..0b15f21 100644 --- a/charts/pyxis/templates/driver-deployment.yaml +++ b/charts/pyxis/templates/driver-deployment.yaml @@ -7,7 +7,7 @@ metadata: labels: {{- include "pyxis.labels" (dict "root" . "part" "driver") | nindent 4 }} spec: - # チューナーを占有するので 1 つだけ動かし、入れ替えも古いものが止まってから + # チューナーを占有するのでレプリカは 1 つだけにし、更新のときも古い Pod が停止してから新しい Pod を起動する replicas: 1 strategy: type: Recreate @@ -26,7 +26,7 @@ spec: {{- if $driver.hostNetwork }} hostNetwork: true {{- end }} - # 録画中に止められると録画の終わりまで待つ。shutdownGraceHours より長くする + # 録画中に停止を要求されると録画の終了まで待つ。shutdownGraceHours より長くする terminationGracePeriodSeconds: {{ $driver.terminationGracePeriodSeconds }} containers: - name: driver diff --git a/charts/pyxis/templates/pvc.yaml b/charts/pyxis/templates/pvc.yaml index 057bbfc..4e9f39b 100644 --- a/charts/pyxis/templates/pvc.yaml +++ b/charts/pyxis/templates/pvc.yaml @@ -17,7 +17,7 @@ metadata: labels: {{- include "pyxis.labels" (dict "root" $ "part" $name) | nindent 4 }} annotations: - # リリースを消しても残す + # リリースを削除しても PVC を残す helm.sh/resource-policy: keep spec: accessModes: diff --git a/charts/pyxis/templates/vela-deployment.yaml b/charts/pyxis/templates/vela-deployment.yaml index d9f9a69..b08f567 100644 --- a/charts/pyxis/templates/vela-deployment.yaml +++ b/charts/pyxis/templates/vela-deployment.yaml @@ -25,7 +25,7 @@ spec: env: - name: CARINA_API_BASE_URL value: {{ printf "http://%s:8080" (include "pyxis.partName" (dict "root" . "part" "app")) | quote }} - # next の standalone は HOSTNAME で待ち受ける。k8s は Pod 名を入れるので全部で待ち受けさせる + # Next.js の standalone サーバは HOSTNAME のアドレスで待ち受ける。Kubernetes は HOSTNAME に Pod 名を入れるので、0.0.0.0 を指定してすべてのインターフェースで待ち受ける - name: HOSTNAME value: 0.0.0.0 ports: diff --git a/charts/pyxis/values.yaml b/charts/pyxis/values.yaml index dd87e6c..6772b24 100644 --- a/charts/pyxis/values.yaml +++ b/charts/pyxis/values.yaml @@ -1,12 +1,12 @@ -# 全部の Pod に当てる nodeSelector。driver と app はソケットのディレクトリを hostPath で共有するので、ノードが複数なら同じノードを指す +# すべての Pod に適用する nodeSelector。driver と app はソケットのディレクトリを hostPath で共有するので、ノードが複数なら同じノードを指定する nodeSelector: {} -# イメージを引くときに使う Secret の名前の一覧。GHCR の公開イメージなら要らない +# イメージの pull に使う Secret の名前の一覧。GHCR の公開イメージなら要らない imagePullSecrets: [] carina: - # app を動かす uid。鍵の置き場やエンコード済みファイルの持ち主になる + # app を動かす uid。鍵のディレクトリやエンコード済みファイルの所有者になる uid: 10001 - # app を動かす gid。driver のソケットの所有グループ (driver.json の socketGroupId) にも同じ値を入れる + # app を動かす gid。driver のソケットの所有グループ (driver.json の socketGroupId) にもチャートが同じ値を設定する gid: 10001 driver: @@ -15,20 +15,20 @@ driver: image: # driver のイメージ repository: ghcr.io/newworldorg/puppis - # driver のイメージのタグ。compose.yml と同じ版にする + # driver のイメージのタグ。compose.yml と同じバージョンにする tag: v0.3.0 - # イメージを引く条件 + # イメージの pull ポリシー pullPolicy: IfNotPresent - # driver.json の中身をそのまま書く。socketGroupId はチャートが carina.gid で入れ、socketPath は既定 (/run/carina/driver.sock) のままにする + # driver.json の内容をそのまま書く。socketGroupId はチャートが carina.gid の値を設定し、socketPath は既定 (/run/carina/driver.sock) のままにする config: # 録画の保存先。app の Integrity__OutputRoots と同じ名前とパスにする outputRoots: - name: primary path: /srv/recordings - # 録画中に止められたとき、録画の終わりを待つ上限の時間 + # 録画中に停止を要求されたとき、録画の終了を待つ時間の上限 shutdownGraceHours: 6 tuner: - # dvb、usb か fake。置いてあるのは合成のチューナー + # dvb、usb、fake のどれか。既定はテスト用の擬似チューナー (fake) backend: fake # チューナーの一覧。dvb と usb なら devicePath も書く devices: @@ -38,7 +38,7 @@ driver: - id: fake-satellite kind: satellite enabled: true - # ホストの装置のディレクトリの一覧。同じパスで hostPath で渡す (/dev/dvb/adapter0 や /dev/bus/usb) + # ホストのデバイスのディレクトリの一覧。同じパスに hostPath でマウントする (/dev/dvb/adapter0 や /dev/bus/usb) hostDevices: [] pcscd: # ホストの pcscd の /run/pcscd をディレクトリごと読み取り専用で渡すか。tuner.backend が dvb なら要る @@ -46,16 +46,16 @@ driver: socket: # driver と app が共有するソケットのディレクトリのホスト側のパス。無ければ作る hostPath: /run/pyxis - # ホストのネットワークで動かすか。カードを貸す driver は true にして、口を Pod の網の外に開く + # ホストのネットワークで動かすか。カードを貸す driver は true にして、ポートを Pod のネットワークの外に公開する hostNetwork: false lendingKey: # カードの貸し借りの鍵を持つ Secret の名前。空なら渡さない existingSecret: "" - # その Secret の中の鍵のキー。/etc/puppis/lending.key に所有者だけが読める形で置く + # その Secret の中で鍵を持つキー。/etc/puppis/lending.key に所有者だけが読めるパーミッションでマウントする key: key - # 止めるときに録画の終わりを待つ秒数。config.shutdownGraceHours より長くする + # 停止するときに録画の終了を待つ秒数。config.shutdownGraceHours より長くする terminationGracePeriodSeconds: 25200 - # driver だけに当てる nodeSelector。空なら上の nodeSelector を使う + # driver だけに適用する nodeSelector。空なら最上位の nodeSelector を使う nodeSelector: {} # driver の resources resources: {} @@ -66,42 +66,42 @@ app: image: # app と migrate のイメージ repository: ghcr.io/newworldorg/carina - # app のイメージのタグ。compose.yml と同じ版にする + # app のイメージのタグ。compose.yml と同じバージョンにする tag: v2.1.0 - # イメージを引く条件 + # イメージの pull ポリシー pullPolicy: IfNotPresent - # ブラウザからこのサーバに届くアドレス (https://tv.example.com)。OIDC の redirect URI の元になる + # ブラウザから見たこのサーバのアドレス (https://tv.example.com)。OIDC の redirect URI の元になる publicOrigin: "" - # X-Forwarded-* を信じる前段の網の一覧 (10.42.0.0/16 など)。Ingress のコントローラの Pod がいる網を書く + # X-Forwarded-* を信頼するリバースプロキシのネットワーク (CIDR) の一覧 (10.42.0.0/16 など)。Ingress コントローラの Pod がいるネットワークを書く knownNetworks: [] - # 録画をあとからエンコードするときの変換器。Software、Vaapi、Nvenc のどれか + # 録画をあとからエンコードするときのエンコーダー。Software、Vaapi、Nvenc のどれか encodingsPrefer: Software - # ライブと録画再生をその場で変換するときの変換器。Software、Vaapi、Nvenc のどれか + # ライブと録画再生をリアルタイムでトランスコードするときのエンコーダー。Software、Vaapi、Nvenc のどれか transcodingPrefer: Software gpu: - # GPU の渡し方。none、devicePlugin (Intel の device plugin)、hostPath (/dev/dri を渡し、app を特権にする)、 + # GPU の渡し方。none、devicePlugin (Intel の device plugin)、hostPath (/dev/dri をマウントし、app を特権コンテナにする)、 # nvidia (NVIDIA Container Toolkit と device plugin。Nvenc で使う。ホストのドライバは 530.41.03 以上) mode: none - # devicePlugin のときに要求する資源の名前 + # devicePlugin のときに要求するリソースの名前 resource: gpu.intel.com/i915 # nvidia のときに app に付ける RuntimeClass の名前 runtimeClassName: nvidia - # nvidia のときに要求する資源の名前 + # nvidia のときに要求するリソースの名前 nvidiaResource: nvidia.com/gpu # nvidia のときに要求する GPU の数 nvidiaCount: 1 - # VAAPI (devicePlugin と hostPath) で使う GPU の描画ノード。nvidia では使わない + # VAAPI (devicePlugin と hostPath) で使う GPU の render ノード。nvidia では使わない renderNode: /dev/dri/renderD128 - # hostPath のときにホストから渡す装置のディレクトリ + # hostPath のときにホストからマウントするデバイスのディレクトリ hostPath: /dev/dri dataProtection: - # OIDC の client secret を封じる鍵の種を持つ Secret の名前。鍵の置き場が空のときだけ写す。空なら app が初回に作る + # ASP.NET Core Data Protection の鍵ファイルを持つ Secret の名前。keys のボリュームに同じ名前のファイルが無いときだけコピーする。空なら app が初回に鍵を生成する seedSecret: "" # app に足す環境変数の一覧 (name と value)。Encodings__MostCores などの細かい設定に使う extraEnv: [] - # app だけに当てる nodeSelector。空なら上の nodeSelector を使う + # app だけに適用する nodeSelector。空なら最上位の nodeSelector を使う nodeSelector: {} - # app の resources。devicePlugin と nvidia のときは GPU の資源をチャートが足す + # app の resources。devicePlugin と nvidia のときは GPU のリソースをチャートが追加する resources: {} postgres: @@ -110,9 +110,9 @@ postgres: image: # PostgreSQL のイメージ repository: postgres - # PostgreSQL のイメージのタグ。compose.yml と同じ版にする + # PostgreSQL のイメージのタグ。compose.yml と同じバージョンにする tag: 18.6-trixie - # イメージを引く条件 + # イメージの pull ポリシー pullPolicy: IfNotPresent auth: # データベースの名前 @@ -123,9 +123,9 @@ postgres: existingSecret: "" # その Secret の中のパスワードのキー passwordKey: password - # existingSecret が空のときに Secret に入れるパスワード。`;` は使えない。どちらも空だと描画が止まる + # existingSecret が空のときに Secret に入れるパスワード。`;` は使えない。どちらも空だとレンダリングが失敗する password: "" - # データベースだけに当てる nodeSelector。空なら上の nodeSelector を使う + # データベースだけに適用する nodeSelector。空なら最上位の nodeSelector を使う nodeSelector: {} # データベースの resources resources: {} @@ -137,29 +137,29 @@ externalDatabase: connectionKey: connection vela: - # 画面の Deployment と Service を作るか + # Vela の Deployment と Service を作るか enabled: true image: - # 画面のイメージ + # Vela のイメージ repository: ghcr.io/newworldorg/vela - # 画面のイメージのタグ。compose.yml と同じ版にする + # Vela のイメージのタグ。compose.yml と同じバージョンにする tag: v1.4.0 - # イメージを引く条件 + # イメージの pull ポリシー pullPolicy: IfNotPresent - # 画面だけに当てる nodeSelector。空なら上の nodeSelector を使う + # Vela だけに適用する nodeSelector。空なら最上位の nodeSelector を使う nodeSelector: {} - # 画面の resources + # Vela の resources resources: {} route: - # 前段の種類。ingress (標準の Ingress)、ingressRoute (Traefik の IngressRoute)、none (自前の前段) + # 外部からのリクエストを app と Vela に振り分けるリソースの種類。ingress (標準の Ingress)、ingressRoute (Traefik の IngressRoute)、none (作らず、リバースプロキシを自分で用意する) kind: ingress - # ブラウザが開くホスト名 (tv.example.com)。空ならホスト名を見ずに全部を受ける + # ブラウザが開くホスト名 (tv.example.com)。空ならホスト名を問わず、すべてのリクエストを受ける host: "" ingress: # Ingress の ingressClassName。空なら書かない className: "" - # Ingress の annotations。SSE と WebSocket を溜めない設定はコントローラごとに違う + # Ingress の annotations。SSE と WebSocket をバッファリングしない設定は Ingress コントローラごとに違う annotations: {} # Ingress の tls の一覧 (hosts と secretName) tls: [] @@ -170,12 +170,12 @@ route: # IngressRoute の tls。{} なら Traefik の既定の証明書、null なら http tls: {} -# 置き場ごとに type を pvc、existingClaim、hostPath から選ぶ。thumbnails と captions は emptyDir も選べる +# ボリュームごとに type を pvc、existingClaim、hostPath から選ぶ。thumbnails と captions は emptyDir も選べる persistence: recordings: - # 録画。driver が書き、app は読むだけ + # 録画。driver が書き込み、app は読み取り専用でマウントする type: pvc - # pvc のときの大きさ + # pvc のときのサイズ size: 500Gi # pvc のときの storageClassName。空なら既定、"-" なら無し storageClass: "" @@ -187,12 +187,12 @@ persistence: hostPath: # hostPath のときのホスト側のパス path: "" - # hostPath のときの type。Directory なら無いときに起動しない + # hostPath のときの type。Directory ならディレクトリが無いと Pod が起動しない type: Directory encodes: - # エンコード済みのファイル。app が書く + # エンコード済みのファイル。app が書き込む type: pvc - # pvc のときの大きさ + # pvc のときのサイズ size: 200Gi # pvc のときの storageClassName。空なら既定、"-" なら無し storageClass: "" @@ -207,9 +207,9 @@ persistence: # hostPath のときの type type: Directory thumbnails: - # サムネイル。app が書く。emptyDir なら Pod と一緒に消え、作り直される + # サムネイル。app が書き込む。emptyDir なら Pod と一緒に消え、再生成される type: pvc - # pvc のときの大きさ + # pvc のときのサイズ size: 5Gi # pvc のときの storageClassName。空なら既定、"-" なら無し storageClass: "" @@ -224,9 +224,9 @@ persistence: # hostPath のときの type type: Directory captions: - # 録画から取り出した字幕とデータ放送の記録。app が書く。emptyDir なら Pod と一緒に消え、取り出し直される + # 録画から抽出した字幕とデータ放送の記録。app が書き込む。emptyDir なら Pod と一緒に消え、抽出し直される type: pvc - # pvc のときの大きさ + # pvc のときのサイズ size: 5Gi # pvc のときの storageClassName。空なら既定、"-" なら無し storageClass: "" @@ -241,9 +241,9 @@ persistence: # hostPath のときの type type: Directory keys: - # OIDC の client secret を封じる鍵。データベースとは別に残す + # OIDC の client secret や通知の送り先を暗号化する鍵 (ASP.NET Core Data Protection) と、Web Push の署名に使う鍵。データベースとは別にバックアップする type: pvc - # pvc のときの大きさ + # pvc のときのサイズ size: 100Mi # pvc のときの storageClassName。空なら既定、"-" なら無し storageClass: "" @@ -260,7 +260,7 @@ persistence: db: # 同梱のデータベースのデータ type: pvc - # pvc のときの大きさ + # pvc のときのサイズ size: 20Gi # pvc のときの storageClassName。空なら既定、"-" なら無し storageClass: "" diff --git a/compose.yml b/compose.yml index 6e4345a..7879236 100644 --- a/compose.yml +++ b/compose.yml @@ -22,7 +22,7 @@ services: retries: 10 start_period: 1m - # app は uid 10001 で動くので、app が書く置き場の所有者をその番号にそろえてから app を上げる (中のファイルには触らない) + # app は uid 10001 で動くので、app が書き込むディレクトリとボリュームの所有者を 10001 にしてから app を起動する (中のファイルの所有者は変えない) prepare: image: ghcr.io/newworldorg/carina:v2.1.0 logging: *logging @@ -54,7 +54,7 @@ services: ConnectionStrings__Carina: Host=db;Port=5432;Database=carina;Username=carina;Password=${POSTGRES_PASSWORD:?} CARINA_DATA_PROTECTION_KEYS: /var/lib/carina/keys CARINA_PUBLIC_ORIGIN: ${CARINA_PUBLIC_ORIGIN:-} - # proxy はこの compose の網にいる。networks の subnet と同じ値にする + # proxy はこの compose のネットワークにいる。networks の subnet と同じ値にする CARINA_KNOWN_NETWORKS: 172.30.0.0/24 Integrity__OutputRoots: primary=/srv/recordings Thumbnails__WrittenTo: /srv/thumbnails @@ -94,10 +94,10 @@ services: driver: image: ghcr.io/newworldorg/puppis:v0.3.0 logging: *logging - # 要求による停止は 0、それ以外は 70 で終わるので on-failure は使わない + # 停止を要求されたときは終了コード 0、それ以外は 70 で終了するので on-failure は使わない restart: unless-stopped privileged: true - # 録画中に止められると録画の終わり (上限 shutdownGraceHours、既定 6 時間) まで待つ。それより長くする + # 録画中に停止を要求されると録画の終了 (上限は shutdownGraceHours、既定 6 時間) まで待つ。それより長くする stop_grace_period: 7h environment: PUPPIS_DRIVER_CONFIG: /etc/puppis/driver.json diff --git a/examples/gpu-intel.yml b/examples/gpu-intel.yml index 0af02c2..8ee5086 100644 --- a/examples/gpu-intel.yml +++ b/examples/gpu-intel.yml @@ -1,6 +1,6 @@ # Intel の GPU (VAAPI) を app に渡す。 -# 描画ノードの所有グループは、イメージの entrypoint が装置から読んで app に足すので group_add は要らない。 -# 渡しただけでは変換はソフトウェアのままなので、.env で CARINA_ENCODINGS_PREFER と CARINA_TRANSCODING_PREFER を Vaapi にする +# render ノード (/dev/dri/renderD128 など) の所有グループは、イメージの entrypoint がデバイスから読み取って app に追加するので group_add は要らない。 +# 渡しただけではエンコーダーは Software のままなので、.env で CARINA_ENCODINGS_PREFER と CARINA_TRANSCODING_PREFER を Vaapi にする services: app: devices: diff --git a/examples/gpu-nvidia.yml b/examples/gpu-nvidia.yml index 63d1d55..e5ef754 100644 --- a/examples/gpu-nvidia.yml +++ b/examples/gpu-nvidia.yml @@ -1,6 +1,6 @@ # NVIDIA の GPU (NVENC) を app に渡す。ホストに NVIDIA Container Toolkit と 530.41.03 以上のドライバが要る。 -# ドライバのライブラリはランタイムがホストから差し込む。video が無いと libnvidia-encode が入らない。 -# 渡しただけでは変換はソフトウェアのままなので、.env で CARINA_ENCODINGS_PREFER と CARINA_TRANSCODING_PREFER を Nvenc にする +# ドライバのライブラリは NVIDIA のコンテナランタイムがホストからマウントする。video が無いと libnvidia-encode がマウントされない。 +# 渡しただけではエンコーダーは Software のままなので、.env で CARINA_ENCODINGS_PREFER と CARINA_TRANSCODING_PREFER を Nvenc にする services: app: environment: diff --git a/examples/tuner-dvb.yml b/examples/tuner-dvb.yml index 3f22487..cbf87fd 100644 --- a/examples/tuner-dvb.yml +++ b/examples/tuner-dvb.yml @@ -1,9 +1,9 @@ # Linux DVB のチューナーと B-CAS カード (ホストの pcscd) を driver に渡す。 -# チューナーが増えたら devices の行を足し、driver/driver.json の devices にも同じ装置を書く +# チューナーが増えたら devices の行を足し、driver/driver.json の devices にも同じデバイスを書く services: driver: devices: - /dev/dvb/adapter0:/dev/dvb/adapter0 volumes: - # pcscd は起動し直すたびにソケットを作り直すので、ファイルではなくディレクトリごと渡す + # pcscd は再起動のたびにソケットを作り直すので、ファイルではなくディレクトリごとマウントする - /run/pcscd:/run/pcscd:ro diff --git a/examples/tuner-usb.yml b/examples/tuner-usb.yml index a9d97f3..92dcaf2 100644 --- a/examples/tuner-usb.yml +++ b/examples/tuner-usb.yml @@ -1,6 +1,6 @@ # USB の地上デジタルチューナー (CECH-ZD1) を driver に渡す。 -# 挿し直すとノードの番号が変わる。devices で渡すとコンテナを作ったときのノードしか見えないので、 -# /dev/bus/usb をマウントし、USB の装置 (メジャー番号 189) の読み書きを許す +# 挿し直すとデバイスノードの番号が変わる。devices で渡すとコンテナを作成したときのデバイスノードしか見えないので、 +# /dev/bus/usb をマウントし、USB デバイス (メジャー番号 189) へのアクセスを device cgroup で許可する services: driver: device_cgroup_rules: diff --git a/scripts/check-kind.sh b/scripts/check-kind.sh index 01bb822..af889fe 100755 --- a/scripts/check-kind.sh +++ b/scripts/check-kind.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash -# 今の kubectl の context (kind) に、既定の値と ci/kind-sizes.yaml でチャートを入れ、 -# app の /api/health と vela の /login が 200 を返し、app が driver の口 (/events) につないだことを確かめる。 -# 終わったらリリースと名前空間を消す +# 現在の kubectl の context (kind) に、ci/default-values.yaml と ci/kind-sizes.yaml でチャートをインストールし、 +# app の /api/health と vela の /login が 200 を返し、app が driver のエンドポイント (/events) に接続したことを確かめる。 +# 終わったらリリースと名前空間を削除する (PYXIS_KIND_KEEP=1 のときは残す) set -euo pipefail cd "$(dirname "$0")/.." @@ -37,7 +37,7 @@ describe_failure() { } kubectl create namespace "$namespace" --dry-run=client -o yaml | kubectl apply -f - >/dev/null -# driver は privileged で動く +# driver は特権コンテナなので、名前空間の Pod Security を privileged にする kubectl label namespace "$namespace" pod-security.kubernetes.io/enforce=privileged --overwrite >/dev/null if ! helm upgrade --install "$release" charts/pyxis -n "$namespace" \ @@ -70,7 +70,7 @@ fi curl -s "http://127.0.0.1:${app_port}/api/health" echo -# app は driver の口につなぐと、まず /events を購読する。driver の要求のログにそれが残る +# app は driver のソケットに接続すると、まず /events を購読する。driver のリクエストログにそれが残る subscribed='' for _ in $(seq 1 60); do if kubectl -n "$namespace" logs "deploy/${release}-driver" --tail=-1 | grep -q 'GET http://driver/events'; then diff --git a/scripts/check-rendering.sh b/scripts/check-rendering.sh index 2831855..29c9e73 100755 --- a/scripts/check-rendering.sh +++ b/scripts/check-rendering.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash -# チャートの描き方の決まりを、既定の値で描いた結果に対して確かめる。 -# Pod のテンプレートにチャートの版 (helm.sh/chart) を入れない。ConfigMap の checksum は driver の Pod にだけ付ける。 -# リリース名 carina で描くと Service が carina-app・carina-db・carina-vela になる +# チャートのレンダリング結果が満たすべき条件を、ci/default-values.yaml でレンダリングした結果に対して確かめる。 +# Pod のテンプレートにチャートのバージョン (helm.sh/chart) を入れない。ConfigMap の checksum は driver の Pod にだけ付ける。 +# リリース名 carina でレンダリングすると Service が carina-app・carina-db・carina-vela になる set -euo pipefail cd "$(dirname "$0")/.." @@ -29,7 +29,7 @@ if [ "$checksum_owners" != 'carina-driver' ]; then status=1 fi -# チャートの版だけが変わっても driver の checksum は変わらない (変わると版を上げるたびに driver が作り直され、録画が切れる) +# チャートのバージョンだけが変わっても driver の checksum は変わらない (変わるとバージョンを上げるたびに driver の Pod が作り直され、録画が中断する) checksum_of() { printf '%s\n' "$1" | sed -n 's/^ *checksum\/config: *//p' | head -n 1 } @@ -39,7 +39,7 @@ sed -i 's/^version: .*/version: 99.99.99/; s/^appVersion: .*/appVersion: 99.99.9 rebumped=$(helm template carina "$bumped/pyxis" -f charts/pyxis/ci/default-values.yaml) rm -rf "$bumped" if [ "$(checksum_of "$rendered")" != "$(checksum_of "$rebumped")" ]; then - echo 'チャートの版を変えただけで driver の checksum が変わる' >&2 + echo 'チャートのバージョンを変えただけで driver の checksum が変わる' >&2 status=1 fi reconfigured=$(helm template carina charts/pyxis -f charts/pyxis/ci/default-values.yaml --set driver.config.shutdownGraceHours=7) @@ -58,5 +58,5 @@ if [ "$services" != 'carina-app carina-db carina-vela ' ]; then status=1 fi -[ "$status" = 0 ] && echo '描き方の決まりは守られている' +[ "$status" = 0 ] && echo 'レンダリング結果は条件をすべて満たしている' exit "$status" diff --git a/scripts/check-versions.sh b/scripts/check-versions.sh index 3b93413..13d553a 100755 --- a/scripts/check-versions.sh +++ b/scripts/check-versions.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# compose.yml、charts/pyxis/values.yaml、charts/pyxis/Chart.yaml の 3 か所に書いたイメージの版が同じかを確かめる。 -# values.yaml と Chart.yaml のイメージはどれも compose.yml に無ければならず、compose.yml の carina・vela・postgres もその中に無ければならない +# compose.yml、charts/pyxis/values.yaml、charts/pyxis/Chart.yaml の 3 か所に書いたイメージのバージョンが同じかを確かめる。 +# values.yaml と Chart.yaml のイメージはどれも compose.yml に無ければならず、compose.yml の carina・puppis・vela・postgres のイメージも values.yaml と Chart.yaml の両方に無ければならない set -euo pipefail cd "$(dirname "$0")/.." @@ -54,7 +54,7 @@ while IFS= read -r image; do done < <(compose_images) if [ "$status" = 0 ]; then - echo 'compose.yml、values.yaml、Chart.yaml のイメージの版は同じ' + echo 'compose.yml、values.yaml、Chart.yaml のイメージのバージョンは同じ' values_images fi exit "$status" diff --git a/scripts/release-notes.sh b/scripts/release-notes.sh index 1dc14af..fe5e517 100755 --- a/scripts/release-notes.sh +++ b/scripts/release-notes.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# GitHub Release の本文を書く。この版が固定するイメージの表と、前の版から driver が替わるかどうか。 -# 引数は前の版のタグ (無ければ空)。PYXIS_VERSION に出す版 (0.1.0-rc.1 など) を渡す。無ければ Chart.yaml の version +# GitHub Release の本文を標準出力に書く。このバージョンで固定するイメージの表、前のバージョンから driver のイメージが変わるかどうか、更新のコマンド。 +# 引数は前のバージョンのタグ (無ければ空)。PYXIS_VERSION にリリースするバージョン (0.1.0-rc.1 など) を渡す。無ければ Chart.yaml の version を使う set -euo pipefail cd "$(dirname "$0")/.." @@ -30,7 +30,7 @@ row() { printf '| %s | `%s` |\n' "$label" "$image" } -echo '| 部品 | イメージ |' +echo '| コンポーネント | イメージ |' echo '| --- | --- |' row 'Carina' carina-app row 'Puppis (driver)' puppis-driver @@ -41,11 +41,11 @@ echo driver_now=$(image_of HEAD puppis-driver) driver_before=$(image_of "$previous" puppis-driver) if [ -z "$previous" ]; then - echo '最初の版。' + echo '最初のバージョン。' elif [ "$driver_now" = "$driver_before" ]; then echo "driver のイメージは ${previous} と同じ。更新しても driver は作り直されず、録画は続く。" else - echo "driver のイメージが ${previous} の \`${driver_before}\` から替わる。録画中とライブの視聴中を避けて更新する。" + echo "driver のイメージが ${previous} の \`${driver_before}\` から変わる。録画中とライブの視聴中を避けて更新する。" fi echo version=${PYXIS_VERSION:-$(sed -n 's/^version: *//p' charts/pyxis/Chart.yaml)}