使用 ORAS 來管理 OCI 成品和供應鏈成品

發行項
10/16/2024

Azure Container Registry (ACR) 可協助您管理開放容器計畫 (OCI) 成品和供應鏈成品。本文會指導您如何使用 ACR 來有效地管理 OCI 成品和供應鏈成品。了解如何儲存、管理及擷取 OCI 成品和供應鏈成品圖，包括簽章、軟體物料清單 (SBOM)、安全性掃描結果和其他類型。

本文分為兩個主要章節：

必要條件

Azure 容器登錄庫 - 在 Azure 訂用帳戶中建立容器登錄庫。例如，使用 Azure 入口網站或 Azure CLI。
Azure CLI - 需要版本 2.29.1 或更新版本。如需安裝和/或升級，請參閱安裝 Azure CLI (部分機器翻譯)。
ORAS CLI - 需要 v1.1.0 版或更新版本。請參閱：ORAS 安裝。
Docker (選擇性) - 若要逐步完成，會參考容器映像。 CLI 會 oras 利用 Docker 桌面認證存放區來儲存認證。您可以使用本機安裝的 Docker 來建置和推送容器映像，或使用 acr build 在 Azure 中遠端建置。

設定登錄

若要設定您的環境以輕鬆執行命令，請遵循下列步驟：

將 ACR_NAME 變數設定為您的登錄名稱。
將 REGISTRY 變數設定為 $ACR_NAME.azurecr.io。
將 REPO 變數設定為您的存放庫名稱。
將 TAG 變數設定為您所需的標籤。
將 IMAGE 變數設定為 $REGISTRY/${REPO}:$TAG。

設定環境變數

設定登錄名稱、登入認證、存放庫名稱和標籤以推送和提取成品。下列範例會使用 net-monitor 存放庫名稱和 v1 標籤。將取代為您自己的存放庫名稱和標籤。

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io
REPO=net-monitor
TAG=v1
IMAGE=$REGISTRY/${REPO}:$TAG

使用 ACR 進行驗證，以允許您提取和推送容器映像。

az login  
az acr login -n $REGISTRY

此設定可讓您將成品無縫地推送到您的 Azure Container Registry 或從您的 Azure Container Registry 中提取成品。現在，ORAS 可以搭配 ACR 使用，而不需使用 oras login 命令進行其他驗證。

如果 Docker 無法使用，您可以使用提供的 AD 令牌進行驗證。使用 AD 權杖透過個別 Microsoft Entra 身分識別進行驗證。一律使用 "000..." 做為 USER_NAME，因為權杖會透過 PASSWORD 變數進行剖析。所使用的 az acr login 令牌有效期限為三小時。

注意

ACR 和 ORAS 支援使用者和系統自動化的多個驗證選項。本文使用個別身分識別來方便示範。如需更多驗證選項，請參閱使用 Azure 容器登錄進行驗證。

使用 ORAS 推送和提取 OCI 成品

您可以使用 Azure Container Registry 來儲存和管理 Open Container Initiative (OCI) 成品，以及 Docker 和 OCI 容器映像。

為了示範此功能，本節說明如何使用 OCI Registry as Storage (ORAS) CLI，將 OCI 成品推送到 Azure Container Registry 或從 Azure Container Registry 中提取 OCI 成品。您可以使用適用於每個成品的不同命令列工具，在 Azure Container Registry 中管理各種 OCI 成品。

提取成品

沒有 subject 父代的單一檔案成品可以是容器映像、Helm 圖表、存放庫讀我檔案中的任何項目。參考成品可以是簽章、軟體物料清單、掃描報告或其他進化型別的任何項目。參考成品，如附加、推送和提取供應鏈成品中所述，是參考另一個成品的成品。

推送單一檔案成品

在此範例中，建立代表 Markdown 檔案的內容：

echo 'Readme Content' > readme.md

下列步驟會將 readme.md 檔案推送至 <myregistry>.azurecr.io/samples/artifact:readme。

登錄會識別為完整登錄名稱 <myregistry>.azurecr.io (全部小寫)，後接命名空間與存放庫 /samples/artifact。
成品會有 :readme 標籤，以將其與存放庫 (:latest, :v1, :v1.0.1) 中列出的其他成品區別。
設定 --artifact-type readme/example 可區分成品與容器映像，映像會使用 application/vnd.oci.image.config.v1+json。
./readme.md 可識別上傳的檔案，而 :application/markdown 代表檔案的 IANA mediaType。
如需詳細資訊，請參閱 OCI 成品作者指引 (英文)。

使用 oras push 命令，將此檔案推送至您的登錄。

Linux、WSL2 或 macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example \
    ./readme.md:application/markdown

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown

成功推送的輸出類似下列輸出：

Uploading 2fdeac43552b readme.md
Uploaded  2fdeac43552b readme.md
Pushed <myregistry>.azurecr.io/samples/artifact:readme
Digest: sha256:e2d60d1b171f08bd10e2ed171d56092e39c7bac1

aec5d9dcf7748dd702682d53

推送多檔案成品

將 OCI 成品推送至具有 ORAS 的登錄時，將會推送每個檔案參考做為 Blob。若要推送個別的 Blob，請個別參考檔案，或參考目錄來收集檔案。
如需如何推送檔案集合的詳細資訊，請參閱使用多個檔案推送成品。

建立部分存放庫文件：

echo 'Readme Content' > readme.md
mkdir details/
echo 'Detailed Content' > details/readme-details.md
echo 'More detailed Content' > details/readme-more-details.md

推送多檔案成品：

Linux、WSL2 或 macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example\
    ./readme.md:application/markdown\
    ./details

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

探索資訊清單

若要檢視 oras push 所建立的資訊清單，請使用 oras manifest fetch：

oras manifest fetch --pretty $REGISTRY/samples/artifact:readme

輸出如下：

{
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
  "artifactType": "readme/example",
  "blobs": [
    {
      "mediaType": "application/markdown",
      "digest": "sha256:2fdeac43552b71eb9db534137714c7bad86b53a93c56ca96d4850c9b41b777fc",
      "size": 15,
      "annotations": {
        "org.opencontainers.image.title": "readme.md"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:0d6c7434a34f6854f971487621426332e6c0fda08040b9e6cc8a93f354cee0b1",
      "size": 189,
      "annotations": {
        "io.deis.oras.content.digest": "sha256:11eceb2e7ac3183ec9109003a7389468ec73ad5ceaec0c4edad0c1b664c5593a",
        "io.deis.oras.content.unpack": "true",
        "org.opencontainers.image.title": "details"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.artifact.created": "2023-01-10T14:44:06Z"
  }
}

提取成品

建立要下載的全新目錄。

mkdir ./download

執行 oras pull 命令，以從登錄中提取成品。

oras pull -o ./download $REGISTRY/samples/artifact:readme

檢視提取的檔案

tree ./download

移除成品 (選擇性)

若要從登錄移除成品，請使用 oras manifest delete 命令。

 oras manifest delete $REGISTRY/samples/artifact:readme

使用 ORAS 附加、推送和提取供應鏈成品

為了示範此功能，本文說明如何使用 OCI Registry as Storage (ORAS) CLI，將供應鏈成品的圖形 push、discover 和 pull 至 Azure Container Registry。儲存個別的 (主體) OCI 成品涵蓋在推送和提取 OCI 成品中。

若要儲存成品圖，則需使用 OCI 映像資訊清單來定義對 subject 成品的參考，該資訊清單是發行前版本 OCI 1.1 散發規格的一部分。

推送容器映像

若要使用 Azure CLI 將成品圖形與容器映像產生關聯：

您可以建置並推送容器映像，或者如果 $IMAGE 參考登錄中的現有映像，則跳過此步驟。

az acr build -r $ACR_NAME -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main

附加簽章

echo '{"artifact": "'${IMAGE}'", "signature": "jayden hancock"}' > signature.json

將簽章附加至登錄，做為容器映像的參考

oras attach 命令會在檔案 (./signature.json) 之間建立 $IMAGE 的參考。 --artifact-type 供用於區分成品，類似於啟用不同檔案類型的副檔名。您可以藉由指定 [file]:[mediaType] 來附加一或多個檔案。

oras attach $IMAGE \
    --artifact-type signature/example \
    ./signature.json:application/json

如需 ORAS 附加的詳細資訊，請參閱 ORAS 文件。

附加多檔案成品做為參考

探索成品參考

OCI v1.1 規格會定義參考者 API，以探索 subject 成品的參考。 oras discover 命令可以顯示容器映像的參考清單。

使用 oras discover，檢視現在儲存在登錄中的成品圖形。

oras discover -o tree $IMAGE

輸出會顯示成品圖形的開頭，其中簽章和文件會視為容器映像的子系。

myregistry.azurecr.io/net-monitor:v1
├── signature/example
│   └── sha256:555ea91f39e7fb30c06f3b7aa483663f067f2950dcb...
└── readme/example
    └── sha256:1a118663d1085e229ff1b2d4d89b5f6d67911f22e55...

建立成品圖

OCI v1.1 規格可啟用深層圖表，以作為啟用簽署的軟體帳單 (SBOM) 和其他成品類型。

以下是建立 SBOM 並將其附加到登錄的方法：

建立範例 SBOM

echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json

將範例 SBOM 附加至登錄中的映像

Linux、WSL2 或 macOS

oras attach $IMAGE \
  --artifact-type sbom/example \
  ./sbom.json:application/json

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type sbom/example ^
    ./sbom.json:application/json

簽署 SBOM

重要

Microsoft 建議使用安全的加密簽署工具 (例如 Notation) 來對映像進行簽署並產生用於簽署 SBOM 的簽章。

成品會以參考來推送，通常不會有標籤，因為其被視為 subject 成品的一部分。若要將簽章推送至另一個成品的子系，請使用 oras discover 搭配 --artifact-type 篩選來尋找摘要。此範例會使用簡單的 JSON 簽章來進行示範。

SBOM_DIGEST=$(oras discover -o json \
                --artifact-type sbom/example \
                $IMAGE | jq -r ".manifests[0].digest")

建立 SBOM 的簽章。

echo '{"artifact": "'$IMAGE@$SBOM_DIGEST'", "signature": "jayden hancock"}' > sbom-signature.json

附加 SBOM 簽章

oras attach $IMAGE@$SBOM_DIGEST \
  --artifact-type 'signature/example' \
  ./sbom-signature.json:application/json

檢視圖表

oras discover -o tree $IMAGE

它會產生下列輸出：

myregistry.azurecr.io/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

提升成品圖

一般的 DevOps 工作流程會將成品從開發環境提升到暫存環境，最後提升到生產環境。安全的供應鏈工作流程會將公用內容提升至私人安全的環境。在任一情況下，您都希望將簽章、SBOM、掃描結果和其他相關成品與主體成品一起提升，以獲得完整的相依性圖形。

使用 oras copy 命令，您可以跨登錄升階已篩選的成品圖表。

將 net-monitor:v1 映像及相關的成品複製到 sample-staging/net-monitor:v1：

TARGET_REPO=$REGISTRY/sample-staging/$REPO
oras copy -r $IMAGE $TARGET_REPO:$TAG

oras copy 的輸出：

Copying 6bdea3cdc730 sbom-signature.json
Copying 78e159e81c6b sbom.json
Copied  6bdea3cdc730 sbom-signature.json
Copied  78e159e81c6b sbom.json
Copying 7cf1385c7f4d signature.json
Copied  7cf1385c7f4d signature.json
Copying 3e797ecd0697 details
Copying 2fdeac43552b readme.md
Copied  3e797ecd0697 details
Copied  2fdeac43552b readme.md
Copied demo42.myregistry.io/net-monitor:v1 => myregistry.azurecr.io/sample-staging/net-monitor:v1
Digest: sha256:ff858b2ea3cdf4373cba65d2ca6bcede4da1d620503a547cab5916614080c763

探索升階的成品圖表

oras discover -o tree $TARGET_REPO:$TAG

oras discover 的輸出：

myregistry.azurecr.io/sample-staging/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

提取參考的成品

若要提取特定參考成品，會使用命令 oras discover 探索參考摘要：

DOC_DIGEST=$(oras discover -o json \
              --artifact-type 'readme/example' \
              $TARGET_REPO:$TAG | jq -r ".manifests[0].digest")

建立要下載的全新目錄

mkdir ./download

將文件提取至下載目錄

oras pull -o ./download $TARGET_REPO@$DOC_DIGEST

檢視文件

tree ./download

tree 的輸出：

./download
├── details
│   ├── readme-details.md
│   └── readme-more-details.md
└── readme.md

檢視存放庫和標籤清單

ORAS 可讓成品圖形推送、探索、提取和複製，而不需要指派標籤。它也可讓標籤清單專注於使用者考慮的成品，而不是與容器映像、Helm 圖表和其他成品相關聯的簽章和 SBOM。

檢視標籤清單

oras repo tags $REGISTRY/$REPO

刪除圖中的所有成品

支援 OCI v1.1 規格可讓您刪除與主體成品建立關聯的成品圖形。使用 oras manifest delete 命令來刪除成品的圖形 (簽章、SBOM 和 SBOM 的簽章)。

oras manifest delete -f $REGISTRY/$REPO:$TAG

oras manifest delete -f $REGISTRY/sample-staging/$REPO:$TAG

您可以檢視資訊清單的清單以確認刪除主體成品以及所有相關成品留下乾淨的環境。

az acr manifest list-metadata \
  --name $REPO \
  --registry $ACR_NAME -o jsonc

輸出：

2023-01-10 18:38:45.366387 Error: repository "net-monitor" is not found.

摘要

在本文中，您已了解如何使用 Azure Container Registry 來儲存、管理及擷取 OCI 成品和供應鏈成品。您使用了 ORAS CLI 將成品推送到 Azure Container Registry 或從 Azure Container Registry 中提取成品。您也探索了已推送成品的資訊清單，並檢視了附加到容器映像的成品圖。

下一步

了解成品參考、關聯簽章、軟體物料清單和其他參考型別。
深入了解 ORAS 專案 (英文)，包括如何設定成品的資訊清單。
如需有關新成品類型的參考資訊，請造訪 OCI 成品 (英文) 存放庫。

共用方式為

使用 ORAS 來管理 OCI 成品和供應鏈成品

必要條件

設定登錄

設定環境變數

使用 ORAS 推送和提取 OCI 成品

提取成品

推送單一檔案成品

推送多檔案成品

探索資訊清單

提取成品

檢視提取的檔案

移除成品 (選擇性)

使用 ORAS 附加、推送和提取供應鏈成品

推送容器映像

附加簽章

將簽章附加至登錄，做為容器映像的參考

附加多檔案成品做為參考

探索成品參考

建立成品圖

建立範例 SBOM

將範例 SBOM 附加至登錄中的映像

簽署 SBOM

附加 SBOM 簽章

檢視圖表

提升成品圖

探索升階的成品圖表

提取參考的成品

建立要下載的全新目錄

將文件提取至下載目錄

檢視文件

檢視存放庫和標籤清單

檢視標籤清單

刪除圖中的所有成品

摘要

下一步

意見反應

其他資源

共用方式為

使用 ORAS 來管理 OCI 成品和供應鏈成品

必要條件

設定登錄

設定環境變數

登入登錄

使用 ORAS 推送和提取 OCI 成品

提取成品

推送單一檔案成品

推送多檔案成品

探索資訊清單

提取成品

檢視提取的檔案

移除成品 (選擇性)

使用 ORAS 附加、推送和提取供應鏈成品

推送容器映像

附加簽章

將簽章附加至登錄，做為容器映像的參考

附加多檔案成品做為參考

探索成品參考

建立成品圖

建立範例 SBOM

將範例 SBOM 附加至登錄中的映像

簽署 SBOM

附加 SBOM 簽章

檢視圖表

提升成品圖

探索升階的成品圖表

提取參考的成品

建立要下載的全新目錄

將文件提取至下載目錄

檢視文件

檢視存放庫和標籤清單

檢視標籤清單

刪除圖中的所有成品

摘要

下一步

意見反應

其他資源