離線安裝(Air-gapped)
適用情境
叢集無法連上網際網路時,Kubernetes Job 安裝 與 本機腳本安裝 都無法使用,因為兩者都需要從 GitHub、Helm repository 與公開 Registry 下載內容。
v0.71.0 起,每一個 release 都附帶兩個檔案:
| 檔案 | 內容 |
|---|---|
sentinel-images-<版本>.txt | 該版本需要的所有 Image:K8s Sentinel、Tetragon、Trivy Operator、Trivy,以及 Trivy 的兩個弱點資料庫 |
sentinel-offline-<版本>.tar.gz | Manifest 與腳本。不含 Image,因此檔案很小 |
離線套件只會安裝 Image 清單所列的版本:Tetragon 與 Trivy Operator 在 release 建置時就已經從各自的 chart 轉成 manifest,因此叢集端只需要 kubectl,不需要 Helm。
整個流程分為三步:
- 在可連網的機器上下載離線套件並儲存 Image
- 把整個目錄帶到離線環境,將 Image 推送到叢集節點可拉取的私有 Registry
- 以
install.sh --registry安裝
開始之前
| 項目 | 說明 |
|---|---|
| 私有 Registry | 叢集節點可以拉取的 Registry(例如 Harbor)。使用 Harbor 時,請先建立要存放 Image 的 project(下方範例為 sentinel) |
| 不需認證即可拉取 | 節點與 Trivy 都必須能在沒有認證的情況下從該 Registry 拉取。離線套件不會設定 image pull secret |
| 節點信任 Registry 的憑證 | 這是每個節點上 container runtime 的設定(containerd 的 certs.d),離線套件不會更動。若其他工作負載已經從這個 Registry 拉取 Image,表示已經設定完成 |
| 搬運 Image 的工具 | 可連網與離線兩端的機器都只需要 docker 或 podman(v0.74+),兩者都有時使用 docker,腳本會顯示實際使用的是哪一個。Trivy 的弱點資料庫是 OCI artifact,docker 與 podman 都無法當成 Image 拉取或推送,因此腳本會以容器 Image(quay.io/skopeo/stable:v1.18)執行 skopeo 來搬運;save 會把這個 Image 一併存下來,讓 push 在離線環境也能使用。它只是腳本的工具,不會被推送到你的 Registry |
| 先登入 Registry | 執行 push 之前,請先在該機器上登入 Registry(docker login、podman login) |
| CPU 架構 | Image 是依執行 save 那台機器的 CPU 架構儲存的,請在與叢集節點相同架構的機器上執行 |
| 叢集前置需求 | 與線上安裝相同:Kubernetes 1.32+、Cilium(啟用 kube-proxy replacement 與 Hubble),見 前置需求。Cilium 不在離線套件內,需自行以離線方式安裝 |
Registry 中缺少 Trivy 的兩個資料庫時,K8s Sentinel 仍可安裝並正常運作,但沒有任何 Image 能被掃描。v0.73 以前的 mirror-images.sh 需要機器上另外裝有 skopeo 或 oras 才能搬運資料庫;v0.74 起腳本會自行處理,只需要 docker 或 podman。
步驟一:在可連網的機器上下載並儲存 Image
從 release 頁面下載離線套件(以下以 v0.75.0 為例,請換成要安裝的版本):
curl -LO https://github.com/cooloo9871/K8s_Sentinel/releases/download/v0.75.0/sentinel-offline-v0.75.0.tar.gz
tar xzf sentinel-offline-v0.75.0.tar.gz
cd sentinel-offline-v0.75.0
bash mirror-images.sh save # 約 2 GB,存入 ./images
套件解開後的內容:
| 檔案 | 用途 |
|---|---|
images.txt | Image 清單,與 release 上的 sentinel-images-<版本>.txt 相同 |
mirror-images.sh | 儲存(save)與推送(push)Image |
install.sh | 離線安裝腳本 |
uninstall.sh | 解除安裝腳本,見 解除安裝 |
manifests/ | sentinel.yaml、tetragon.yaml、tetragon-grpc-policy.yaml、trivy-operator.yaml、trivy-operator-crds.yaml(v0.75+) |
VERSION | 套件版本 |
以 v0.75.0 為例,images.txt 列出的內容為:
ghcr.io/cooloo9871/sentinel:v0.75.0
mirror.gcr.io/aquasec/trivy:0.76.1
mirror.gcr.io/aquasec/trivy-operator:0.36.1
quay.io/cilium/hubble-export-stdout:v1.1.1
quay.io/cilium/tetragon-operator:v1.8.0
quay.io/cilium/tetragon:v1.8.0
# artifacts
mirror.gcr.io/aquasec/trivy-db:2
mirror.gcr.io/aquasec/trivy-java-db:1
最後兩項是 Trivy 的弱點資料庫(OCI artifact)。
步驟二:把 Image 推送到私有 Registry
把整個 sentinel-offline-<版本> 目錄(含 images/)帶到離線環境,在可以連到 Registry 的機器上執行:
bash mirror-images.sh push harbor.example.com/sentinel
Registry 參數是「主機加路徑」,不含 http:// 或 https://。
Registry 使用 HTTP,或憑證不被這台機器信任(出現 x509: certificate signed by unknown authority)時,加上 --insecure-registry(v0.73+):
bash mirror-images.sh push harbor.example.com/sentinel --insecure-registry
這只影響推送的這台機器,不會改變叢集信任什麼。使用 docker 時,還需要把該 Registry 列在 daemon 設定的 insecure-registries,因為 docker 沒有針對單一指令的開關。
Image 在 Registry 中保留原本的路徑,只把最前面的 Registry 主機換掉:
| 原始位置 | 推送後的位置 |
|---|---|
quay.io/cilium/tetragon:v1.8.0 | harbor.example.com/sentinel/cilium/tetragon:v1.8.0 |
ghcr.io/cooloo9871/sentinel:v0.75.0 | harbor.example.com/sentinel/cooloo9871/sentinel:v0.75.0 |
mirror.gcr.io/aquasec/trivy-db:2 | harbor.example.com/sentinel/aquasec/trivy-db:2 |
同一台機器若能同時連到網際網路與 Registry,可以一次完成:
bash mirror-images.sh save && bash mirror-images.sh push harbor.example.com/sentinel
mirror-images.sh 可用的環境變數:
| 環境變數 | 說明 |
|---|---|
INSECURE=1 | 效果與 push 的 --insecure-registry 相同(v0.72 以前只有這個寫法) |
CONTAINER_CLI | 指定要使用的指令,取代自動偵測的 docker / podman,例如 CONTAINER_CLI=podman 或 CONTAINER_CLI="sudo podman" |
IMAGES_DIR | Image 的存放目錄,預設為套件內的 ./images |
步驟三:安裝
在可以用 kubectl 存取叢集的機器上執行:
bash install.sh --registry harbor.example.com/sentinel
腳本會把 manifest 中的每一個 Image 改寫為私有 Registry 的位置,再依序執行:
- Tetragon:叢集任一 Namespace 已有 Tetragon DaemonSet 時跳過;否則套用
tetragon.yaml並等待就緒。接著套用 NetworkPolicytetragon-grpc - K8s Sentinel:套用
sentinel.yaml並等待 Deployment 就緒 - Trivy Operator:叢集任一 Namespace 已有 Trivy Operator 時跳過;否則安裝至
sentinel-system。v0.75 起會先套用 CRD 並等待 API Server 開始提供,再套用其餘物件
在沒有 Trivy Operator 的叢集上,v0.74 以前的 install.sh 會以 no matches for kind "ClusterComplianceReport" 結束,並在等待 Operator 就緒之前停止。這樣結束的安裝,K8s Sentinel 會用到的部分都已完成,不需要重新執行;v0.75.0 已修正。
與線上安裝程式相同,叢集中既有的 Tetragon 或 Trivy Operator 不會被更動。既有的 Tetragon 需要自行設定 K8s Sentinel 所需的 gRPC 位址,見 安裝 Tetragon。
| 選項 | 說明 |
|---|---|
--registry <主機/路徑> | 必填。mirror-images.sh push 推送的位置 |
--render-only <目錄> | 把將要套用的 manifest 寫入該目錄,不套用任何內容。適合先檢視,或以自己的方式套用 |
--insecure-registry | v0.72.0+。Registry 的憑證由自有 CA 簽發、或使用 HTTP 時使用,見下一節 |
離線套件中的 K8s Sentinel 與線上安裝有三處不同:
- Image 固定為該 release 的版本標籤,而不是
latest;imagePullPolicy為IfNotPresent - Deployment 已設定
TRIVY_IMAGE、TRIVY_DB_REPOSITORY、TRIVY_JAVA_DB_REPOSITORY,因此 Registry 掃描 會使用與 Trivy Operator 相同的 Trivy 與資料庫,同樣指向私有 Registry - Tetragon 與 Trivy Operator 是以 manifest 套用,叢集中沒有 Helm release
安裝完成後的存取方式與線上安裝相同:
kubectl port-forward -n sentinel-system svc/sentinel 8080:80
接著請依 首次登入 變更預設密碼,正式環境並請完成 設定永久儲存。
Registry 使用自有 CA 或 HTTP
節點與 Trivy 是分開信任 Registry 的:
| 誰在拉取 | 依據什麼信任 Registry |
|---|---|
| 節點的 container runtime(拉取所有 Pod 的 Image) | 節點自己的設定(containerd 的 certs.d)。離線套件與 --insecure-registry 都不會處理這一項 |
| Trivy(下載弱點資料庫、讀取要掃描的 Image) | Trivy 在 Pod 內執行,不使用節點的設定。憑證必須來自公開 CA,否則要以 --insecure-registry 安裝 |
bash install.sh --registry harbor.example.com/sentinel --insecure-registry
加上 --insecure-registry(v0.72.0+)後,Trivy 下載資料庫與讀取要掃描的 Image 時都不驗證憑證。
這會關閉 Trivy 所有的憑證驗證,包含它掃描的其他 Registry,而不只是存放資料庫的這一台。
對應到 K8s Sentinel 自己的 Registry 掃描,--insecure-registry 會在 Deployment 上設定環境變數 TRIVY_INSECURE=true。
更新弱點資料庫
弱點資料庫每天更新,但離線環境中的掃描只認得儲存資料庫當天以前公布的弱點。請排程定期重新執行 save 與 push,更新私有 Registry 中的副本。
升級
升級與安裝相同:下載新版 release 的離線套件,重新執行上述三個步驟。
install.sh 會重新套用 K8s Sentinel 的 manifest,因此 安裝概覽 中「重新套用 deploy/sentinel.yaml」的注意事項在這裡同樣適用:若你曾修改 Deployment 或 Service(例如改掛 PVC、改為 NodePort),請先用 --render-only 產生 manifest,把修改帶進去之後再套用。
解除安裝
使用離線套件內的 uninstall.sh,選項與行為見 解除安裝:
bash uninstall.sh --dry-run
bash uninstall.sh
自行建置離線套件
需要自行產生離線套件時(例如尚未發佈的版本),可在可連網且有 Helm 的機器上,於 K8s Sentinel 原始碼目錄執行:
bash deploy/offline/build.sh v0.75.0
產出的兩個檔案位於 dist/。Tetragon 與 Trivy Operator 的 chart 版本定義在 deploy/offline/versions.env。