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

發行項
05/30/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 (選擇性) - 若要逐步完成，會參考容器映像。您可以使用本機安裝的 Docker 來建置和推送容器映像，或使用 acr build 在 Azure 中遠端建置。
雖然不需要 Docker Desktop，但 oras CLI 會利用 Docker 桌面認證存放區來儲存認證。如果已安裝 Docker Desktop，其必須針對 oras login 執行。

設定登錄

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

將 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

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

# Login to Azure
az login

將認證提供給 oras login。

oras login $REGISTRY \
    --username $USER_NAME \
    --password $PASSWORD

此設定可讓您順暢地推送和提取 Azure Container Registry 中的成品。視需要調整特定組態的變數。

使用 ORAS 推送和提取 OCI 成品

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

為了示範這項功能，本節示範如何使用 OCI 登錄作為儲存體（ORAS） CLI，以推送和提取 Azure 容器登錄的 OCI 成品。您可以使用適用於每個成品的不同命令列工具，在 Azure Container Registry 中管理各種 OCI 成品。

注意

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

推送成品

沒有 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 登錄作為儲存體（ORAS） CLI，pushdiscover以及 pull Azure 容器登錄的供應鏈成品圖表。儲存個別的（主旨） 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 建議使用安全的密碼編譯簽署工具，例如表示法來簽署映像，並產生簽署 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 中來回推送和提取成品。您也會探索已推送成品的指令清單，並檢視連結至容器映射的成品圖形。

下一步

瞭解成品參考、關聯簽章、軟體材料帳單和其他參考類型。
深入瞭解 ORAS 專案，包括如何設定成品的指令清單。
如需新成品類型的參考資訊，請造訪 OCI Artifacts 存放庫。

共用方式為

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

必要條件

設定登錄

設定環境變數

使用 ORAS 推送和提取 OCI 成品

推送成品

推送單一檔案成品

推送多檔案成品

探索資訊清單

提取成品

檢視提取的檔案

移除成品 (選擇性)

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

推送容器映像

附加簽章

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

附加多檔案成品做為參考

探索成品參考

建立成品圖形

建立範例 SBOM

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

簽署 SBOM

附加 SBOM 簽章

檢視圖表

升級成品圖形

探索升階的成品圖表

提取參考的成品

建立要下載的全新目錄

將文件提取至下載目錄

檢視文件

檢視存放庫和標籤清單

檢視標籤清單

刪除圖形中的所有成品

摘要

下一步

其他資源

共用方式為

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

必要條件

設定登錄

設定環境變數

登入登錄

使用 ORAS 登入

使用 ORAS 推送和提取 OCI 成品

推送成品

推送單一檔案成品

推送多檔案成品

探索資訊清單

提取成品

檢視提取的檔案

移除成品 (選擇性)

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

推送容器映像

附加簽章

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

附加多檔案成品做為參考

探索成品參考

建立成品圖形

建立範例 SBOM

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

簽署 SBOM

附加 SBOM 簽章

檢視圖表

升級成品圖形

探索升階的成品圖表

提取參考的成品

建立要下載的全新目錄

將文件提取至下載目錄

檢視文件

檢視存放庫和標籤清單

檢視標籤清單

刪除圖形中的所有成品

摘要

下一步

其他資源