使用 Azure 登錄，推送或提取供應鏈成品 (預覽)

發行項
04/26/2024

使用 Azure 容器登錄來儲存和管理供應鏈成品的圖表，包括簽章、軟體材料帳單 (SBOM)、安全性掃描結果或其他類型。

Graph of artifacts, including a container image, signature and signed software bill of materials

為了示範這項功能，本文說明如何使用 OCI Registry 做為儲存體 (ORAS) CLI，將供應鏈成品的圖形 push、discover 和 pull 至 Azure 容器登錄。儲存個別的 (根) OCI 成品涵蓋在推送和提取 OCI 成品中。

若要儲存成品圖表，會使用 OCI 成品資訊清單來定義 subject 成品的參考，該資訊清單是發行前版本 OCI 1.1 散發規格的一部分。 OCI 1.1 成品資訊清單支援是 ACR 預覽功能，並受限制。

必要條件

Azure 容器登錄庫 - 在 Azure 訂用帳戶中建立容器登錄庫。例如，使用 Azure 入口網站或 Azure CLI。
請參閱 Azure 雲端支援的預覽限制。
Azure CLI - 需要 2.29.1 版本或更新版本。如需安裝和/或升級，請參閱安裝 Azure CLI。
ORAS CLI - 需要 v0.16.0 版本。請參閱：ORAS 安裝。
Docker (選擇性) - 若要逐步完成，會參考容器映像。您可以使用本機安裝的 Docker 來建置和推送容器映像，或使用 acr build 在 Azure 中遠端建置。
雖然不需要 Docker Desktop，但 oras CLI 會利用 Docker 桌面認證存放區來儲存認證。如果已安裝 Docker Desktop，其必須針對 oras login 執行。

預覽限制

OCI 成品資訊清單支援 (OCI 1.1 規格) 適用於所有 Azure 公用區域。尚不支援由 21Vianet 和政府雲端運作的 Microsoft Azure。

設定登錄

設定環境變數，輕鬆地將命令複製/貼上`到殼層。可以在本機或在 Azure Cloud Shell 中執行命令。

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

使用 AD 權杖透過個別 Microsoft Entra 身分識別進行驗證。一律使用 "000..." 做為 USER_NAME，因為權杖會透過 PASSWORD 變數進行剖析。

# Login to Azure
az login

# Login to ACR, using a token based on your Azure identity
USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)

注意

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

將認證提供給 oras login。

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

推送容器映像

此範例會將成品圖形與容器映像建立關聯。

如果 $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 成品推送至具有 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

附加多檔案成品做為 $IMAGE 的參考：

Linux、WSL2 或 macOS

oras attach $IMAGE \
    --artifact-type readme/example \
    ./readme.md:application/markdown \
    ./details

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

探索成品參考

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

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

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

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

檢視存放庫和標籤清單

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

檢視標籤清單

oras repo tags $REGISTRY/$REPO

檢視資訊清單的清單

存放庫可以存有已標記和未標記之資訊清單的清單。使用 az acr manifest CLI，檢視完整資訊清單的清單：

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

請注意容器映像資訊清單具有 "tags"，而參考型別 ("mediaType": "application/vnd.oci.artifact.manifest.v1+json") 則沒有。

在輸出中，簽章已取消標記，但會以 oci.artifact.manifest 做為容器映像的參考：

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2023-01-10T17:58:28.4403142Z",
  "digest": "sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5",
  "imageSize": 80,
  "lastUpdateTime": "2023-01-10T17:58:28.4403142Z",
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json"
}

刪除圖形中的所有成品

支援 OCI v1.1 規格可讓您刪除與根成品建立關聯的成品圖形。使用 oras 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.

摘要

在本文中，會建立、探索、升階和提取供應鏈成品圖表，以提供您所建置和相依成品的生命週期管理。

下一步

深入了解 ORAS CLI
深入了解 OCI 成品資訊清單，如何推送、探索、提取、複製供應鏈成品的圖表

Share via

使用 Azure 登錄，推送或提取供應鏈成品 (預覽)

必要條件

預覽限制

設定登錄

推送容器映像

建立容器映像的範例簽章

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

附加多檔案成品做為參考

探索成品參考

建立成品的深層圖表

建立範例 SBOM

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

簽署 SBOM

附加 SBOM 簽章

檢視圖表

升階圖表

探索升階的成品圖表

提取參考的成品

建立要下載的全新目錄

將文件提取至下載目錄

檢視文件

檢視存放庫和標籤清單

檢視標籤清單

檢視資訊清單的清單

刪除圖形中的所有成品

檢視其餘的資訊清單

摘要

下一步

其他資源

Share via

使用 Azure 登錄，推送或提取供應鏈成品 (預覽)

必要條件

預覽限制

設定登錄

使用 ORAS 登入

推送容器映像

建立容器映像的範例簽章

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

附加多檔案成品做為參考

探索成品參考

建立成品的深層圖表

建立範例 SBOM

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

簽署 SBOM

附加 SBOM 簽章

檢視圖表

升階圖表

探索升階的成品圖表

提取參考的成品

建立要下載的全新目錄

將文件提取至下載目錄

檢視文件

檢視存放庫和標籤清單

檢視標籤清單

檢視資訊清單的清單

刪除圖形中的所有成品

檢視其餘的資訊清單

摘要

下一步

其他資源