Merge branch 'main' of https://github.com/Azure/acr
This commit is contained in:
dlepow
Коммит
d58e9ca139
|
|
@ -7,15 +7,22 @@ title: "AAD Integration"
|
|||
|
||||
<!-- TOC depthFrom:2 orderedList:false -->
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Authenticating to a registry with Azure CLI](#authenticating-to-a-registry-with-azure-cli)
|
||||
- [Listing a repository with Azure CLI](#listing-a-repository-with-azure-cli)
|
||||
- [Calling `POST /oauth2/exchange` to get an ACR refresh token](#calling-post-oauth2exchange-to-get-an-acr-refresh-token)
|
||||
- [Authenticating docker with an ACR refresh token](#authenticating-docker-with-an-acr-refresh-token)
|
||||
- [Calling `POST /oauth2/token` to get an ACR access token](#calling-post-oauth2token-to-get-an-acr-access-token)
|
||||
- [Calling `POST /oauth2/token` to get an ACR access token for Helm repository](#calling-post-oauth2token-to-get-an-acr-access-token-for-helm-repository)
|
||||
- [Calling an Azure Container Registry API](#calling-an-azure-container-registry-api)
|
||||
- [Samples API Call scripts](#samples-api-call-scripts)
|
||||
- [Azure Container Registry integration with Azure Active Directory](#azure-container-registry-integration-with-azure-active-directory)
|
||||
- [Overview](#overview)
|
||||
- [Authenticating to a registry with Azure CLI](#authenticating-to-a-registry-with-azure-cli)
|
||||
- [Listing a repository with Azure CLI](#listing-a-repository-with-azure-cli)
|
||||
- [Azure Container Registry token claim sets](#azure-container-registry-token-claim-sets)
|
||||
- [Getting credentials programmatically](#getting-credentials-programmatically)
|
||||
- [Calling `POST /oauth2/exchange` to get an ACR refresh token](#calling-post-oauth2exchange-to-get-an-acr-refresh-token)
|
||||
- [Authenticating docker with an ACR refresh token](#authenticating-docker-with-an-acr-refresh-token)
|
||||
- [Calling `POST /oauth2/token` to get an ACR access token](#calling-post-oauth2token-to-get-an-acr-access-token)
|
||||
- [Calling `POST /oauth2/token` to get an ACR access token for Helm repository](#calling-post-oauth2token-to-get-an-acr-access-token-for-helm-repository)
|
||||
- [Calling an Azure Container Registry API](#calling-an-azure-container-registry-api)
|
||||
- [Catalog Listing](#catalog-listing)
|
||||
- [Pagination](#pagination)
|
||||
- [Tag Listing](#tag-listing)
|
||||
- [Pagination](#pagination-1)
|
||||
- [Samples API Call scripts](#samples-api-call-scripts)
|
||||
- [Catalog Listing with AAD refresh token](#catalog-listing-with-aad-refresh-token)
|
||||
- [Catalog listing using SP/Admin with Basic Auth](#catalog-listing-using-spadmin-with-basic-auth)
|
||||
- [Catalog listing using Admin Keys with Bearer Auth](#catalog-listing-using-admin-keys-with-bearer-auth)
|
||||
|
|
@ -30,7 +37,7 @@ The Azure Container Registry allows users to manage a private Docker registry on
|
|||
|
||||
The integration of Azure Container Registry with Azure Active Directory is crucial in order to enable transparent authentication and authorization of users and headless services using AAD credentials. In this scenario, a user will only have to use their AAD credentials to log-in to their private registry, and the Azure Container Service will take care of the authorization validation of each operation using the provided credentials.
|
||||
|
||||
Under the hood Azure Container Service utilizes the [oauth2](https://oauth.net/2/) authorization protocol, as described by the [Docker Registry v2 authentication via central service documentation](https://docs.docker.com/registry/spec/auth/token/) as well as the [Docker Registry v2 Bearer token specification](https://docs.docker.com/registry/spec/auth/jwt/). The JWT tokens generated by the Azure Container Registry are easy to observe in [jwt.io](https://jwt.io/).
|
||||
Under the hood Azure Container Service utilizes the [oauth2](https://oauth.net/2/) authorization protocol, as described by the [Docker Registry v2 authentication via central service documentation](https://docs.docker.com/registry/spec/auth/token/) as well as the [Docker Registry v2 Bearer token specification](https://docs.docker.com/registry/spec/auth/jwt/). The JWT tokens generated by the Azure Container Registry are easy to observe in [jwt.ms](https://jwt.ms/).
|
||||
|
||||
## Authenticating to a registry with Azure CLI
|
||||
|
||||
|
|
@ -70,15 +77,15 @@ Internally, the CLI will follow these steps:
|
|||
|
||||
When listing the tags of a repository, every step above is the same except for the call to the endpoint that gives the tags which is `GET /v2/contosoregistry/tags/list` instead of `GET /v2/_catalog`.
|
||||
|
||||
# Azure Container Registry refresh tokens and access tokens
|
||||
# Azure Container Registry token claim sets
|
||||
|
||||
Let's follow an example call to list a repository:
|
||||
Following the command of repository list in the previous section:
|
||||
|
||||
```bash
|
||||
az acr repository list -n contosoregistry
|
||||
```
|
||||
|
||||
This will produce a JWT refresh token with the following payload:
|
||||
A JWT refresh token extracted at step 5 has the following claim set:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -90,19 +97,19 @@ This will produce a JWT refresh token with the following payload:
|
|||
"iss": "Azure Container Registry",
|
||||
"aud": "contosoregistry.azurecr.io",
|
||||
"version": "1.0",
|
||||
"grant_type": "access_token_refresh_token",
|
||||
"grant_type": "refresh_token",
|
||||
"tenant": "409520d4-8100-4d1d-ad47-72432ddcc120",
|
||||
"credential": "AQA...iAA",
|
||||
"permissions": {
|
||||
"actions": [
|
||||
"*"
|
||||
],
|
||||
"notActions": []
|
||||
}
|
||||
},
|
||||
"roles": []
|
||||
}
|
||||
```
|
||||
|
||||
Followed by an access token with the following payload:
|
||||
Followed by an access token at step 7 with the following claim set:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -113,6 +120,7 @@ Followed by an access token with the following payload:
|
|||
"iat": 1497988907,
|
||||
"iss": "Azure Container Registry",
|
||||
"aud": "contosoregistry.azurecr.io",
|
||||
"version": "1.0",
|
||||
"access": [
|
||||
{
|
||||
"type": "registry",
|
||||
|
|
@ -121,23 +129,27 @@ Followed by an access token with the following payload:
|
|||
"*"
|
||||
]
|
||||
}
|
||||
]
|
||||
],
|
||||
"roles": [],
|
||||
"grant_type": "access_token"
|
||||
}
|
||||
```
|
||||
|
||||
# Getting credentials programatically
|
||||
# Getting credentials programmatically
|
||||
|
||||
In order to sign in to a container you'll need to exchange AAD credentials for ACR credentials. The accepted form of credential exchange are:
|
||||
- AAD access token.
|
||||
- AAD refresh token.
|
||||
- AAD access token and refresh token.
|
||||
- [Deprecated] AAD refresh token.
|
||||
- [Deprecated] AAD access token and refresh token.
|
||||
|
||||
Ideally you'll present both the AAD access token and the AAD refresh token. The AAD access token is used to talk to the Azure Resource Manager and query for the set of permissions that the user has for the container registry resource. The AAD refresh token is used in two ways:
|
||||
The AAD access token is used to talk to the Azure Resource Manager and query for the set of permissions that the user has for the container registry resource.
|
||||
|
||||
[Deprecated] The AAD refresh token is used in two ways:
|
||||
1. If no AAD access token was presented, the AAD refresh token is used to obtain an AAD access token.
|
||||
2. The AAD refresh token is sent back to the user so they can initiate a token refresh cycle against AAD. If no AAD refresh token is sent, then the client won't have this credential at hand to initiate a credential refresh.
|
||||
|
||||
The cycle to get credentials looks as follows:
|
||||
1. Call `POST /oauth2/exchange` presenting the AAD refresh token and the AAD access token. The service will return you an ACR refresh token.
|
||||
1. Call `POST /oauth2/exchange` presenting the AAD access token or the AAD refresh token [Deprecated]. The service will return you an ACR refresh token.
|
||||
2. Call `POST /oauth2/token` presenting the ACR refresh token. The service will return you an ACR access token which you can use to call the Azure Container Registry's APIs.
|
||||
|
||||
## Calling `POST /oauth2/exchange` to get an ACR refresh token
|
||||
|
|
@ -145,9 +157,9 @@ The cycle to get credentials looks as follows:
|
|||
In this example, we'll try to obtain an ACR refresh token from existing AAD tokens. Assume you have the following:
|
||||
1. A valid container registry, which here we'll call `contosoregistry.azurecr.io`.
|
||||
2. The AAD tenant identifier associated to the credentials, which here we'll take to be `409520d4-8100-4d1d-ad47-72432ddcc120`.
|
||||
3. Valid AAD access token and AAD refresh token credentials with access to the aforementioned container registry.
|
||||
3. Valid AAD access token credential with access to the aforementioned container registry.
|
||||
|
||||
The AAD access token and AAD refresh token can be obtained from the Azure CLI. After running `az login` check file `$HOME/.azure/accessTokens.json` (`%HOMEDRIVE%%HOMEPATH%\.azure\accessTokens.json` in Windows) for the token values.
|
||||
The AAD access token can be obtained from the Azure CLI. After running `az login` check file `$HOME/.azure/accessTokens.json` (`%HOMEDRIVE%%HOMEPATH%\.azure\accessTokens.json` in Windows) for the token values.
|
||||
|
||||
We'll now call `POST /oauth2/exchange` to exchange the AAD tokens for an ACR refresh token. Here's how such a call looks when done via `curl`:
|
||||
```bash
|
||||
|
|
@ -160,11 +172,12 @@ curl -v -X POST -H "Content-Type: application/x-www-form-urlencoded" -d \
|
|||
```
|
||||
|
||||
The body of the POST message is a querystring-like text that specifies the following values:
|
||||
- `grant_type`, which can take a value of `access_token_refresh_token`, or `access_token`, or `refresh_token`.
|
||||
- `grant_type`, which can take a value of `access_token`, or `access_token_refresh_token` [Deprecated], or `refresh_token` [Deprecated].
|
||||
- `service`, which must indicate the name of your Azure container registry.
|
||||
- `tenant`, which is the AAD tenant associated to the AAD credentials.
|
||||
- `refresh_token`, the AAD refresh token, mandatory when `grant_type` is `access_token_refresh_token` or `refresh_token`.
|
||||
- `access_token`, the AAD access token, mandatory when `grant_type` is `access_token_refresh_token` or `access_token`.
|
||||
- `access_token`, the AAD access token, mandatory when `grant_type` is `access_token` or `access_token_refresh_token` [Deprecated].
|
||||
- [Deprecated] `refresh_token`, the AAD refresh token, mandatory when `grant_type` is `access_token_refresh_token` or `refresh_token`.
|
||||
|
||||
|
||||
The outcome of this operation will be a response with status 200 OK and a body with the following JSON payload:
|
||||
|
||||
|
|
@ -172,7 +185,7 @@ The outcome of this operation will be a response with status 200 OK and a body w
|
|||
{"refresh_token":"eyJ...L7a"}
|
||||
```
|
||||
|
||||
This response is the ACR refresh token which you can inspect with [jwt.io](https://jwt.io/). You can now use it to obtain an ACR access token programmatically or simply send it to the `docker login` command to get docker talking to the Azure Container Registry.
|
||||
This response is the ACR refresh token which you can inspect with [jwt.ms](https://jwt.ms/). You can now use it to obtain an ACR access token programmatically or simply send it to the `docker login` command to get docker talking to the Azure Container Registry.
|
||||
|
||||
## Authenticating docker with an ACR refresh token
|
||||
|
||||
|
|
@ -247,7 +260,7 @@ The outcome of this operation will be a response with status 200 OK and a body w
|
|||
```json
|
||||
{"access_token":"eyJ...xcg"}
|
||||
```
|
||||
This response is the ACR access token which you can inspect with [jwt.io](https://jwt.io/). You can now use it to call APIs exposed by the Azure Container Registry
|
||||
This response is the ACR access token which you can inspect with [jwt.ms](https://jwt.ms/). You can now use it to call APIs exposed by the Azure Container Registry
|
||||
|
||||
## Calling `POST /oauth2/token` to get an ACR access token for Helm repository
|
||||
|
||||
|
|
@ -304,7 +317,7 @@ The outcome of this operation will be a response with status 200 OK and a body w
|
|||
{"access_token":"eyJ...xcg"}
|
||||
```
|
||||
|
||||
This response is the ACR access token which you can inspect with [jwt.io](https://jwt.io/). You can now use it to call APIs exposed by the Azure Container Registry. Refer the full script to [fetch the helm index.yaml](#fetch-helm-indexyaml).
|
||||
This response is the ACR access token which you can inspect with [jwt.ms](https://jwt.ms/). You can now use it to call APIs exposed by the Azure Container Registry. Refer the full script to [fetch the helm index.yaml](#fetch-helm-indexyaml).
|
||||
|
||||
## Calling an Azure Container Registry API
|
||||
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ The outcome of this operation will be a response with status 200 OK and a body w
|
|||
{"access_token":"eyJ...xcg"}
|
||||
```
|
||||
|
||||
This response is the ACR access token which you can inspect with [jwt.io](https://jwt.io/). You can now use it to call APIs exposed by the Azure Container Registry.
|
||||
This response is the ACR access token which you can inspect with [jwt.ms](https://jwt.ms/). You can now use it to call APIs exposed by the Azure Container Registry.
|
||||
|
||||
### Calling an Azure Container Registry API
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,61 @@
|
|||
# Set up AKS to pull from ACR in a different AD tenant
|
||||
|
||||
## Introduction
|
||||
|
||||
There are several ways to set up the auth credential in Kubernetes to pull image from ACR. For example, you can use [admin user or repository scoped access token](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal) to configure pod [imagePullSecrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
|
||||
|
||||
While `imagePullSecrets` is commonly used, it brings the challenge and overhead to manage the corresponding secret. On Azure, you can set up [AKS cluster with a service principal credential](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal) which allows you securely pull the image from ACR without additional `imagePullSecrets` setting on each pod.
|
||||
|
||||
Sometimes, you may have your AKS and ACR in different Azure Active Directories (Tenants). This document will walk your through the steps to enable cross tenant authentication using service principal credential.
|
||||
|
||||
## Instruction
|
||||
|
||||
In this example, the AKS cluster is in `Tenant A` and the ACR is in `Tenant B`.
|
||||
|
||||
`Tenant A` is also the service principal home tenant.
|
||||
|
||||
You will need the contributor role of AKS subscription and the owner role of ACR subscription.
|
||||
|
||||
### Step 1: Enable multi-tenant AAD Application
|
||||
|
||||
- Login [Azure portal](http://portal.azure.com/) in `Tenant A` and go to Azure Active Directory `App registrations` blade to find the service principal application object.
|
||||
|
||||
- Remember the `Application (client) ID` (it will be used in `step 2` and `step 4`)
|
||||
|
||||
|
||||
|
||||
- Choose multitenant account type as the following screenshot and also remember the `redirect url` (it will be used in step 2).
|
||||
|
||||
|
||||
|
||||
- Create a client secret if not exist (It is __IMPORTANT__ to make sure you use this client secret to update AKS in `step 4`).
|
||||
|
||||
|
||||
|
||||
|
||||
### Step 2: Provision the service principal in ACR Tenant
|
||||
|
||||
- Open the following link with the Tenant B admin account and accept the permission request.
|
||||
|
||||
```
|
||||
https://login.microsoftonline.com/<ACR Tenant ID (Tenant B)>/oauth2/authorize?client_id=<Application (client) ID>&response_type=code&redirect_uri=<redirect url>
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Step 3: Grant service principal ACR image pull permission
|
||||
|
||||
- Assign AcrPull role to the service principal
|
||||
|
||||
|
||||
|
||||
### Step 4: Update AKS with the AAD Application secret
|
||||
|
||||
- Use the `Application (client) ID` and `client secret` collected in `step 1` to [update AKS service principal credential](https://docs.microsoft.com/en-us/azure/aks/update-credentials#update-aks-cluster-with-new-service-principal-credentials).
|
||||
|
||||
## Reference
|
||||
|
||||
- [Application and service principal objects in Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals)
|
||||
|
||||
|
||||
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 150 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 230 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 102 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 47 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 40 KiB |
|
|
@ -31,7 +31,6 @@ The stamp name is one of the aliases returned by the above command. Currently, c
|
|||
|
||||
Here is a list of known limitations for the connected registry functionality in limited preview:
|
||||
|
||||
- Nested connected registry mode is still under development and requires additional testing. Currently nested registries are blocked and will be released in a few weeks.
|
||||
- Number of tokens and scopemaps is limited to 20K for a single ACR. This indirectly limits the number of connected registries for an ACR registry because every connected registry needs a sync and client token.
|
||||
- Number of repository permissions in a scope map is limited to 500.
|
||||
- Number of clients for the connected registry is currently limited to 20.
|
||||
|
|
@ -58,6 +57,7 @@ In limited preview, the connected registry targets IoT scenarios. Below are link
|
|||
- [Using connected registry with Azure IoT Edge](./overview-connected-registry-and-iot-edge.md)
|
||||
- [Quickstart: Create a connected registry using Azure Container Registry CLI commands](./quickstart-connected-registry-cli.md)
|
||||
- [Quickstart: Deploy a connected registry to an IoT Edge device](./quickstart-deploy-connected-registry-iot-edge-cli.md)
|
||||
- [Quickstart: Deploy a connected registry to an nested IoT Edge device](./quickstart-deploy-connected-registry-nested-iot-edge-cli.md)
|
||||
- [Quickstart: Pull images from a connected registry](./quickstart-pull-images-from-connected-registry.md)
|
||||
|
||||
## Troubleshooting
|
||||
|
|
|
|||
|
|
@ -38,11 +38,14 @@ In this architecture, the connected registries deployed on each layer are config
|
|||
|
||||
In this overview, you learned about the use of the connected registry in hierarchical IoT Edge scenarios. Continue to the one of the following articles to learn how to configure and deploy a connected registry to your IoT Edge device.
|
||||
|
||||
> [Quickstart - Create connected registry using the CLI][quickstart-connected-registry-cli]
|
||||
> [Quickstart: Create connected registry using the CLI][quickstart-connected-registry-cli]
|
||||
|
||||
> [Quickstart - Deploy a connected registry to an IoT Edge device][overview-connected-registry-and-iot-edge]
|
||||
> [Quickstart: Deploy a connected registry to an IoT Edge device][overview-connected-registry-and-iot-edge]
|
||||
|
||||
> [Quickstart: Deploy connected registry on nested IoT Edge device][quickstart-pull-images-from-connected-registry]
|
||||
|
||||
<!-- LINKS - internal -->
|
||||
[quickstart-connected-registry-cli]:quickstart-connected-registry-cli.md
|
||||
[overview-connected-registry-and-iot-edge]:quickstart-deploy-connected-registry-iot-edge-cli.md
|
||||
[tutorial-nested-iot-edge]: https://docs.microsoft.com/azure/iot-edge/tutorial-nested-iot-edge?view=iotedge-2020-11&tabs=azure-portal
|
||||
[tutorial-nested-iot-edge]: https://docs.microsoft.com/azure/iot-edge/tutorial-nested-iot-edge?view=iotedge-2020-11&tabs=azure-portal
|
||||
[quickstart-connected-registry-nested]: quickstart-deploy-connected-registry-nested-iot-edge-cli.md
|
||||
|
|
@ -47,6 +47,15 @@ az acr create --resource-group myResourceGroup \
|
|||
|
||||
This example creates a *Premium* registry. Connected registries are supported only in the *Premium* tier of Azure container registry. For details on available service tiers, see [Container registry service tiers][container-registry-skus].
|
||||
|
||||
## Enable the dedicated data endpoint for the cloud registry
|
||||
|
||||
For the connected registries to communicate with the cloud registry, the dedicated data endpoint for the Azure Container Registry in the cloud should be enabled by using the [az acr update][az-acr-update] command as follows:
|
||||
|
||||
```azurecli
|
||||
az acr update -n mycontainerregistry001 \
|
||||
--data-endpoint-enabled
|
||||
```
|
||||
|
||||
## Import images into the container registry
|
||||
|
||||
This and subsequent quickstart guides use two repositories:
|
||||
|
|
@ -56,7 +65,10 @@ This and subsequent quickstart guides use two repositories:
|
|||
The easiest way to populate those repositories is to use the `az acr import` command as follows:
|
||||
|
||||
```azurecli
|
||||
az acr import -n mycontainerregistry001 --source mcr.microsoft.com/acr/connected-registry:0.1.0
|
||||
az acr import -n mycontainerregistry001 --source mcr.microsoft.com/acr/connected-registry:0.2.0
|
||||
az acr import -n mycontainerregistry001 --source mcr.microsoft.com/azureiotedge-agent:1.2
|
||||
az acr import -n mycontainerregistry001 --source mcr.microsoft.com/azureiotedge-hub:1.2
|
||||
az acr import -n mycontainerregistry001 --source mcr.microsoft.com/azureiotedge-api-proxy:latest
|
||||
az acr import -n mycontainerregistry001 --source mcr.microsoft.com/hello-world:latest
|
||||
```
|
||||
|
||||
|
|
@ -67,7 +79,7 @@ Create a connected registry using the [az acr connected-registry create][az-acr-
|
|||
```azurecli
|
||||
az acr connected-registry create --registry mycontainerregistry001 \
|
||||
--name myconnectedregistry \
|
||||
--repository "hello-world" "acr/connected-registry"
|
||||
--repository "hello-world" "acr/connected-registry" "azureiotedge-agent" "azureiotedge-hub" "azureiotedge-api-proxy"
|
||||
```
|
||||
|
||||
The above command will create a connected registry resource in Azure and link it to the *mycontainerregistry001* cloud ACR. The *hello-world* and *acr/connected-registry* repositories will be synchronized between the cloud ACR and the registry on premises. Because no `--mode` option is specified for the connected registry, it will allow _pull_ and _push_ functionality by default. Because there is no synchronization schedule defined for this connected registry, both repositories will be synchronized between the cloud registry and the connected registry without interruptions.
|
||||
|
|
@ -81,8 +93,9 @@ You can use the connected registry [az acr connected-registry create][az-acr-con
|
|||
|
||||
```azurecli
|
||||
az acr connected-registry create --registry mycontainerregistry001 \
|
||||
--parent myconnectedregistry \
|
||||
--name myconnectedmirror \
|
||||
--repository "hello-world" "acr/connected-registry" \
|
||||
--repository "hello-world" "acr/connected-registry" "azureiotedge-agent" "azureiotedge-hub" "azureiotedge-api-proxy" \
|
||||
--mode mirror
|
||||
```
|
||||
|
||||
|
|
@ -107,15 +120,6 @@ myconnectedregistry registry
|
|||
myconnectedmirror mirror
|
||||
```
|
||||
|
||||
## Enable the data endpoint for the cloud registry
|
||||
|
||||
For the connected registries to communicate with the cloud registry, the data endpoint for the Azure Container Registry in the cloud should be enabled by using the [az acr update][az-acr-update] command as follows:
|
||||
|
||||
```azurecli
|
||||
az acr update -n mycontainerregistry001 \
|
||||
--data-endpoint-enabled
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
In this quickstart, you used Azure CLI to create a connected registry resources in Azure. Those new connected registry resources are tied to your Azure Container Registry and allow synchronization of artifact between the cloud registry and the on-premises registry. Continue to the connected registry deployment guides to learn how to deploy the connected registry on your on-premises infrastructure.
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ In this quickstart, you use [Azure Container Registry][container-registry-intro]
|
|||
|
||||
## Before you begin
|
||||
|
||||
This tutorial requires an Azure IoT Edge device to be set up upfront. You can use the [Deploy your first IoT Edge module to a virtual Linux device](../iot-edge/quickstart-linux.md) quickstart guide to learn how to deploy a virtual IoT Edge device. The connected registry is deployed as a module on the IoT Edge device.
|
||||
This tutorial requires an Azure IoT Edge device to be set up upfront. You can use the [Deploy your first IoT Edge module to a virtual Linux device](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/iot-edge/quickstart-linux.md) quickstart guide to learn how to deploy a virtual IoT Edge device. The connected registry is deployed as a module on the IoT Edge device.
|
||||
|
||||
Also, make sure that you have created the connected registry resource in Azure as described in the [Create connected registry using the CLI][quickstart-connected-registry-cli] quickstart guide. Both, `registry` and `mirror` modes will work for this scenario.
|
||||
|
||||
|
|
@ -36,21 +36,40 @@ To support nested IoT Edge scenarios, the container image for the connected regi
|
|||
```azurecli
|
||||
az acr import \
|
||||
--name mycontainerregistry001 \
|
||||
--source mcr.microsoft.com/acr/connected-registry:0.1.0
|
||||
--source mcr.microsoft.com/acr/connected-registry:0.3.0
|
||||
```
|
||||
|
||||
To learn more about nested IoT Edge scenarios, please visit [Tutorial: Create a hierarchy of IoT Edge devices (Preview)](../iot-edge/tutorial-nested-iot-edge.md).
|
||||
To learn more about nested IoT Edge scenarios, please visit [Tutorial: Create a hierarchy of IoT Edge devices](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/iot-edge/tutorial-nested-iot-edge.md).
|
||||
|
||||
## Import the IotEdge and API Proxy images into your registry
|
||||
|
||||
To support the connected registry on nested IoT Edge, you need import and set up the IoT and API proxy using the private images from acronpremiot registry.
|
||||
|
||||
Notes: You can import those images from MCR if you don't need create nested connected registry.
|
||||
|
||||
```azurecli
|
||||
az acr import \
|
||||
--name mycontainerregistry001 \
|
||||
--source acronpremiot.azurecr.io/acr/microsoft/azureiotedge-agent:20210609.5 -t azureiotedge-agent:20210609.5
|
||||
|
||||
az acr import \
|
||||
--name mycontainerregistry001 \
|
||||
--source acronpremiot.azurecr.io/acr/microsoft/azureiotedge-hub:20210609.5 -t azureiotedge-hub:20210609.5
|
||||
|
||||
az acr import \
|
||||
--name mycontainerregistry001 \
|
||||
--source acronpremiot.azurecr.io/acr/microsoft/azureiotedge-api-proxy:9.9.9-dev -t azureiotedge-api-proxy:9.9.9-dev
|
||||
```
|
||||
## Create a client token for access to the cloud registry
|
||||
|
||||
The IoT Edge runtime will need to authenticate with the cloud registry to pull the connected registry image and deploy it. First, use the following command to create a scope map for the connected registry image repository:
|
||||
The IoT Edge runtime will need to authenticate with the cloud registry to pull the images and deploy it. First, use the following command to create a scope map for the iotedge, api proxy and connected registry image repository:
|
||||
|
||||
```azurecli
|
||||
az acr scope-map create \
|
||||
--description "Connected registry repo pull scope map." \
|
||||
--name conected-registry-pull \
|
||||
--registry mycontainerregistry001 \
|
||||
--repository "acr/connected-registry" content/read
|
||||
--repository "acr/connected-registry" "azureiotedge-api-proxy" "azureiotedge-agent" "azureiotedge-hub" content/read
|
||||
```
|
||||
|
||||
Next, use the following command to create a client token for the IoT Edge device and associate it to the scope map:
|
||||
|
|
@ -105,23 +124,12 @@ az acr connected-registry install renew-credentials \
|
|||
--name myconnectedregistry \
|
||||
```
|
||||
|
||||
This will return the configuration for the connected registry including the newly generated passwords.
|
||||
This will return the connection string for the connected registry including the newly generated passwords.
|
||||
|
||||
```json
|
||||
{
|
||||
"ACR_PARENT_GATEWAY_ENDPOINT": "mycontainerregistry001.westus2.data.azurecr.io",
|
||||
"ACR_PARENT_LOGIN_SERVER": "mycontainerregistry001.azurecr.io",
|
||||
"ACR_PARENT_PROTOCOL": "https",
|
||||
"ACR_REGISTRY_CERTIFICATE_VOLUME": "<myvolume>",
|
||||
"ACR_REGISTRY_DATA_VOLUME": "<myvolume>",
|
||||
"ACR_REGISTRY_LOGIN_SERVER": "<myloginservername>",
|
||||
"ACR_REGISTRY_NAME": "myconnectedregistry",
|
||||
"ACR_SYNC_TOKEN_NAME": "myconnectedregistry-sync-token",
|
||||
"ACR_SYNC_TOKEN_PASSWORD": {
|
||||
"password1": "s0meCoMPL3xP4$$W0rd001!@#",
|
||||
"password2": "an0TH3rCoMPL3xP4ssW0rd002!"
|
||||
},
|
||||
"ACR_SYNC_TOKEN_USERNAME": "myconnectedregistry-sync-token"
|
||||
"ACR_REGISTRY_CONNECTION_STRING": "ConnectedRegistryName=myconnectedregistry;SyncTokenName=myconnectedregistry-sync-token;SyncTokenPassword=s0meCoMPL3xP4$$W0rd001!@#;ParentGatewayEndpoint=mycontainerregistry001.westus2.data.azurecr.io;ParentEndpointProtocol=https",
|
||||
"ACR_REGISTRY_LOGIN_SERVER": "<Optional: connected registry login server. More info at https://aka.ms/acr/connected-registry>"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -137,9 +145,9 @@ You will need the information for the IoT Edge manifest below.
|
|||
|
||||
## Configure a deployment manifest for IoT Edge
|
||||
|
||||
A deployment manifest is a JSON document that describes which modules to deploy to the IoT Edge device. For more information about how deployment manifests work and how to create them, see [Understand how IoT Edge modules can be used, configured, and reused](../iot-edge/module-composition.md).
|
||||
A deployment manifest is a JSON document that describes which modules to deploy to the IoT Edge device. For more information about how deployment manifests work and how to create them, see [Understand how IoT Edge modules can be used, configured, and reused](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/iot-edge/module-composition.md).
|
||||
|
||||
To deploy the connected registry module using the Azure CLI, save the following deployment manifest locally as a `.json` file.
|
||||
To deploy the connected registry and api proxy module using the Azure CLI, save the following deployment manifest locally as a `.json` file.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -149,31 +157,34 @@ To deploy the connected registry module using the Azure CLI, save the following
|
|||
"modules": {
|
||||
"connected-registry": {
|
||||
"settings": {
|
||||
"image": "mycontainerregistry001.azurecr.io/acr/connected-registry:0.1.0",
|
||||
"image": "mycontainerregistry001.azurecr.io/acr/connected-registry:0.3.0",
|
||||
"createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"],\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"8080\"}]}}}"
|
||||
},
|
||||
"type": "docker",
|
||||
"env": {
|
||||
"ACR_REGISTRY_NAME": {
|
||||
"value": "myconnectedregistry"
|
||||
"ACR_REGISTRY_CONNECTION_STRING": {
|
||||
"value": "ConnectedRegistryName=myconnectedregistry;SyncTokenName=myconnectedregistry-sync-token;SyncTokenPassword=s0meCoMPL3xP4$$W0rd001!@#;ParentGatewayEndpoint=mycontainerregistry001.westus2.data.azurecr.io;ParentEndpointProtocol=https"
|
||||
}
|
||||
},
|
||||
"status": "running",
|
||||
"restartPolicy": "always",
|
||||
"version": "1.0"
|
||||
},
|
||||
"IoTEdgeAPIProxy": {
|
||||
"settings": {
|
||||
"image": "mycontainerregistry001.azurecr.io/azureiotedge-api-proxy:9.9.9-dev",
|
||||
"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8000/tcp\":[{\"HostPort\":\"8000\"}]}}}"
|
||||
},
|
||||
"type": "docker",
|
||||
"env": {
|
||||
"NGINX_DEFAULT_PORT": {
|
||||
"value": "8000"
|
||||
},
|
||||
"ACR_PARENT_GATEWAY_ENDPOINT": {
|
||||
"value": "mycontainerregistry001.westus2.data.azurecr.io"
|
||||
"CONNECTED_ACR_ROUTE_ADDRESS": {
|
||||
"value": "connected-registry:8080"
|
||||
},
|
||||
"ACR_SYNC_TOKEN_NAME": {
|
||||
"value": "myconnectedregistry-sync-token"
|
||||
},
|
||||
"ACR_SYNC_TOKEN_PASSWORD": {
|
||||
"value": "s0meCoMPL3xP4$$W0rd001!@#"
|
||||
},
|
||||
"ACR_REGISTRY_LOGIN_SERVER": {
|
||||
"value": "<use_the_ip_address_of_the_iot_edge_device>"
|
||||
},
|
||||
"ACR_PARENT_PROTOCOL": {
|
||||
"value": "https"
|
||||
},
|
||||
"ACR_PARENT_LOGIN_SERVER": {
|
||||
"value": "mycontainerregistry001.azurecr.io"
|
||||
"BLOB_UPLOAD_ROUTE_ADDRESS": {
|
||||
"value": "AzureBlobStorageonIoTEdge:11002"
|
||||
}
|
||||
},
|
||||
"status": "running",
|
||||
|
|
@ -198,7 +209,7 @@ To deploy the connected registry module using the Azure CLI, save the following
|
|||
"systemModules": {
|
||||
"edgeAgent": {
|
||||
"settings": {
|
||||
"image": "mcr.microsoft.com/azureiotedge-agent:1.0",
|
||||
"image": "mycontainerregistry001.azurecr.io/azureiotedge-agent:20210609.5",
|
||||
"createOptions": ""
|
||||
},
|
||||
"type": "docker",
|
||||
|
|
@ -210,7 +221,7 @@ To deploy the connected registry module using the Azure CLI, save the following
|
|||
},
|
||||
"edgeHub": {
|
||||
"settings": {
|
||||
"image": "mcr.microsoft.com/azureiotedge-hub:1.0",
|
||||
"image": "mycontainerregistry001.azurecr.io/azureiotedge-hub:20210609.5",
|
||||
"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
|
||||
},
|
||||
"type": "docker",
|
||||
|
|
@ -242,9 +253,9 @@ Use the information from the previous sections to update the relevant JSON value
|
|||
|
||||
You will use the file path in the next section when you run the command to apply the configuration to your device.
|
||||
|
||||
## Deploy the connected registry module on IoT Edge
|
||||
## Deploy the connected registry and api proxy modules on IoT Edge
|
||||
|
||||
Use the following command to deploy the connected registry module on the IoT Edge device:
|
||||
Use the following command to deploy the connected registry and api proxy modules on the IoT Edge device:
|
||||
|
||||
```azurecli
|
||||
az iot edge set-modules \
|
||||
|
|
@ -253,7 +264,7 @@ az iot edge set-modules \
|
|||
--content [file path]
|
||||
```
|
||||
|
||||
For more details you can refer to the [Deploy Azure IoT Edge modules with Azure CLI](../iot-edge/how-to-deploy-modules-cli.md) article.
|
||||
For more details you can refer to the [Deploy Azure IoT Edge modules with Azure CLI](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/iot-edge/how-to-deploy-modules-cli.md) article.
|
||||
|
||||
To check the status of the connected registry, use the following CLI command:
|
||||
|
||||
|
|
@ -264,7 +275,11 @@ az acr connected-registry show \
|
|||
--output table
|
||||
```
|
||||
|
||||
You may need to a wait few minutes until the deployment of the connected registry completes.
|
||||
You may need to a wait few minutes until the deployment of the connected registry and api proxy complete.
|
||||
|
||||
Make sure you open the the ports `8000`, `5671`, `8883`. The api proxy will listen on port 8000 configued as `NGINX_DEFAULT_PORT`.
|
||||
|
||||
You can find more information about API Proxy in the [https://github.com/Azure/iotedge/tree/master/edge-modules/api-proxy-module]
|
||||
|
||||
## Next steps
|
||||
|
||||
|
|
@ -272,10 +287,13 @@ In this quickstart, you learned how to deploy a connected registry to an IoT Edg
|
|||
|
||||
> [Quickstart: Pull images from a connected registry][quickstart-pull-images-from-connected-registry]
|
||||
|
||||
> [Quickstart: Deploy connected registry on nested IoT Edge device][quickstart-connected-registry-nested]
|
||||
|
||||
<!-- LINKS - internal -->
|
||||
[az-acr-connected-registry-install]: https://docs.microsoft.com/cli/azure/acr/connected-registry/install?view=azure-cli-latest
|
||||
[az-acr-import]: https://docs.microsoft.com/cli/azure/acr?view=azure-cli-latest#az_acr_import
|
||||
[az-acr-token-credential-generate]: https://docs.microsoft.com/cli/azure/acr/token/credential?view=azure-cli-latest#az_acr_token_credential_generate
|
||||
[container-registry-intro]: container-registry-intro.md
|
||||
[quickstart-pull-images-from-connected-registry]: quickstart-pull-images-from-connected-registry.md
|
||||
[quickstart-connected-registry-cli]: quickstart-connected-registry-cli.md
|
||||
[quickstart-connected-registry-cli]: quickstart-connected-registry-cli.md
|
||||
[quickstart-connected-registry-nested]: quickstart-deploy-connected-registry-nested-iot-edge-cli.md
|
||||
|
|
|
|||
|
|
@ -0,0 +1,310 @@
|
|||
---
|
||||
title: Quickstart - Deploy a connected registry to a nested IoT Edge device
|
||||
description: Use Azure Container Registry CLI commands and Azure portal to deploy a connected registry to a nested Azure IoT Edge device.
|
||||
ms.topic: quickstart
|
||||
ms.date: 04/28/2021
|
||||
ms.author: memladen
|
||||
author: toddysm
|
||||
ms.custom:
|
||||
---
|
||||
|
||||
# Quickstart: Deploy a connected registry to a nested IoT Edge device
|
||||
|
||||
In this quickstart, you use [Azure Container Registry][container-registry-intro] commands to deploy a connected registry to a nested Azure IoT Edge device. You can review the [ACR connected registry introduction](intro-connected-registry.md) for details about the connected registry feature of Azure Container Registry.
|
||||
|
||||
[!INCLUDE [quickstarts](https://docs.microsoft.com/en-us/azure/iot-edge/quickstart-linux?view=iotedge-2018-06)]
|
||||
|
||||
[!INCLUDE [azure-cli-prepare-your-environment.md](https://github.com/MicrosoftDocs/azure-docs/blob/master/includes/azure-cli-prepare-your-environment.md)]
|
||||
|
||||
## Before you begin
|
||||
|
||||
This tutorial also requires that you have the knowledge about set up a connected registry on a IoT Edge device by following the [Quickstart: Deploy a connected registry to an IoT Edge device](quickstart-deploy-connected-registry-iot-edge-cli.md).
|
||||
|
||||
Also, make sure that you have created the connected registry resource in Azure as described in the [Create connected registry using the CLI][quickstart-connected-registry-cli] quickstart guide. Only `mirror` mode will work for this scenario.
|
||||
|
||||
## Retrieve connected registry configuration information
|
||||
|
||||
Before deploying the connected registry to the nested IoT Edge device, you will need to retrieve the configuration from the connected registry resource in Azure. Use the [az acr connected-registry install][az-acr-connected-registry-install] command to retrieve the configuration.
|
||||
|
||||
```azurecli
|
||||
az acr connected-registry install renew-credentials \
|
||||
--registry mycontainerregistry001 \
|
||||
--name myconnectedmirror \
|
||||
```
|
||||
|
||||
This will return the connection string for the connected registry including the newly generated passwords.
|
||||
|
||||
```json
|
||||
{
|
||||
"ACR_REGISTRY_CONNECTION_STRING": "ConnectedRegistryName=myconnectedmirror;SyncTokenName=myconnectedmirror-sync-token;SyncTokenPassword=s0meCoMPL3xP4$$W0rd001!@#;ParentGatewayEndpoint=<parent gateway endpoint>;ParentEndpointProtocol=<http or https>",
|
||||
"ACR_REGISTRY_LOGIN_SERVER": "<Optional: connected registry login server. More info at https://aka.ms/acr/connected-registry>"
|
||||
}
|
||||
```
|
||||
|
||||
The JSON above lists the environment variables that need to be passed to the connected registry container at run time. The following environment variables are optional:
|
||||
|
||||
- `ACR_REGISTRY_LOGIN_SERVER` - this is the hostname or FQDN of the IoT Edge device that hosts the connected registry.
|
||||
|
||||
You will need the information for the IoT Edge manifest below.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Make sure that you save the generated connection string. The connection string contains one-time password that cannot be retrieved. If you issue the command again, new passwords will be generated. You can generate new passwords using the [az acr token credential generate][az-acr-token-credential-generate] command.
|
||||
|
||||
## Configure a deployment manifest for the nested IoT Edge
|
||||
|
||||
A deployment manifest is a JSON document that describes which modules to deploy to the IoT Edge device. For more information about how deployment manifests work and how to create them, see [Understand how IoT Edge modules can be used, configured, and reused](https://docs.microsoft.com/en-us/azure/iot-edge/module-composition?view=iotedge-2020-11#:~:text=The%20IoT%20Edge%20agent%20module,should%20be%20created%20and%20managed.).
|
||||
|
||||
To deploy the connected registry module using the Azure CLI, save the following deployment manifest locally as a `.json` file.
|
||||
|
||||
[!IMPORTANT] In the following deployment manifest, $upstream will be used as the IP or FQDN of the device hosting parent connected registry. However $upstream is not supported in env variable. The connected registry need read env variable ACR_PARENT_GATEWAY_ENDPOINT to get the parent gateway endpoint. Instead of using $upstream, connected registry supports dynamically resolving the IP or FQDN from another env variable. On the nested IoT, there's env variable $IOTEDGE_PARENTHOSTNAME on lower level that is equal to IP or FQDN of the parent device. We can pass this env variable as the value of ACR_PARENT_GATEWAY_ENDPOINT to avoid hardcode the parent IP or FQDN.
|
||||
|
||||
```json
|
||||
{
|
||||
"modulesContent": {
|
||||
"$edgeAgent": {
|
||||
"properties.desired": {
|
||||
"modules": {
|
||||
"connected-registry": {
|
||||
"settings": {
|
||||
"image": "$upstream/acr/connected-registry:0.3.0",
|
||||
"createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\",\"/usr/local/share/ca-certificates:/usr/local/share/ca-certificates\",\"/etc/ssl/certs:/etc/ssl/certs\",\"LogConfig\":{ \"Type\": \"json-file\", \"Config\": {\"max-size\": \"10m\",\"max-file\": \"3\"}}]}}"
|
||||
},
|
||||
"type": "docker",
|
||||
"env": {
|
||||
"ACR_REGISTRY_CONNECTION_STRING": {
|
||||
"value": "ConnectedRegistryName=myconnectedmirror;SyncTokenName=myconnectedmirror-sync-token;SyncTokenPassword=s0meCoMPL3xP4$$W0rd001!@#;ParentGatewayEndpoint=$IOTEDGE_PARENTHOSTNAME;ParentEndpointProtocol=https"
|
||||
}
|
||||
},
|
||||
"status": "running",
|
||||
"restartPolicy": "always",
|
||||
"version": "1.0"
|
||||
},
|
||||
"IoTEdgeApiProxy": {
|
||||
"settings": {
|
||||
"image": "$upstream/azureiotedge-api-proxy:9.9.9-dev",
|
||||
"createOptions": "{\"HostConfig\": {\"PortBindings\": {\"443/tcp\": [{\"HostPort\": \"443\"}]}}}"
|
||||
},
|
||||
"type": "docker",
|
||||
"version": "1.0",
|
||||
"env": {
|
||||
"NGINX_DEFAULT_PORT": {
|
||||
"value": "443"
|
||||
},
|
||||
"CONNECTED_ACR_ROUTE_ADDRESS": {
|
||||
"value": "connectedRegistry:8080"
|
||||
},
|
||||
"NGINX_CONFIG_ENV_VAR_LIST": {
|
||||
"value": "NGINX_DEFAULT_PORT,BLOB_UPLOAD_ROUTE_ADDRESS,CONNECTED_ACR_ROUTE_ADDRESS,IOTEDGE_PARENTHOSTNAME,DOCKER_REQUEST_ROUTE_ADDRESS"
|
||||
},
|
||||
"BLOB_UPLOAD_ROUTE_ADDRESS": {
|
||||
"value": "AzureBlobStorageonIoTEdge:11002"
|
||||
}
|
||||
},
|
||||
"status": "running",
|
||||
"restartPolicy": "always",
|
||||
"startupOrder": 3
|
||||
}
|
||||
},
|
||||
"runtime": {
|
||||
"settings": {
|
||||
"minDockerVersion": "v1.25",
|
||||
"registryCredentials": {
|
||||
"tsmregistry": {
|
||||
"address": "$upstream",
|
||||
"password": "$$$0meCoMPL3xP4$$W0rd001!@#$$",
|
||||
"username": "myconnectedmirror-sync-token"
|
||||
}
|
||||
}
|
||||
},
|
||||
"type": "docker"
|
||||
},
|
||||
"schemaVersion": "1.1",
|
||||
"systemModules": {
|
||||
"edgeAgent": {
|
||||
"settings": {
|
||||
"image": "$upstream/azureiotedge-agent:20210609.5",
|
||||
"createOptions": ""
|
||||
},
|
||||
"type": "docker",
|
||||
"env": {
|
||||
"SendRuntimeQualityTelemetry": {
|
||||
"value": "false"
|
||||
}
|
||||
}
|
||||
},
|
||||
"edgeHub": {
|
||||
"settings": {
|
||||
"image": "$upstream/azureiotedge-hub:20210609.5",
|
||||
"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
|
||||
},
|
||||
"type": "docker",
|
||||
"status": "running",
|
||||
"restartPolicy": "always"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"$edgeHub": {
|
||||
"properties.desired": {
|
||||
"routes": {
|
||||
"route": "FROM /messages/* INTO $upstream"
|
||||
},
|
||||
"schemaVersion": "1.1",
|
||||
"storeAndForwardConfiguration": {
|
||||
"timeToLiveSecs": 7200
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the information from the previous sections to update the relevant JSON values:
|
||||
|
||||
- The environment variable `ACR_REGISTRY_CONNECTION_STRING` needs to be updated with the output from the `az acr connected-registry install renew-credentials` command above. You will need to manually replace the `ParentGatewayEndpoint` with the $IOTEDGE_PARENTHOSTNAME. You will also need to select the proper protocol in `ParentEndpointProtocol`.
|
||||
- For each module in the manifest, you should update the registry endpoint to the $upstream.
|
||||
|
||||
You will use the file path in the next section when you run the command to apply the configuration to your device.
|
||||
|
||||
## Setup and deploy the connected registry module on nested IoT Edge
|
||||
This tutorial requires a nested Azure IoT Edge device to be set up upfront. You can use the [Deploy your first IoT Edge module to a virtual Linux device](https://docs.microsoft.com/en-us/azure/iot-edge/quickstart-linux?view=iotedge-2020-11) quickstart guide to learn how to deploy a virtual IoT Edge device. To create a nested IoT Edge devices, follow the instructions [Tutorial: Create a hierarchy of IoT Edge devices](https://docs.microsoft.com/en-us/azure/iot-edge/tutorial-nested-iot-edge?view=iotedge-2020-11) to learn how to configure hierarchical IoT edge devices. The connected registry is deployed as a module on the nested IoT Edge device.
|
||||
|
||||
Based on the tutorial, it overall includes the following steps:
|
||||
1. Create top level and lower level vms from existing template. The template will also install the iot agent on it. You can use the [Tutorial: Install or uninstall Azure IoT Edge for Linux](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge?view=iotedge-2020-11) to learn how to manually set up the machine if you need deploy from your own devices.
|
||||
|
||||
2. Use the iotedge-config tool to create and configure your hierarchy, follow the steps below in the Azure CLI:
|
||||
|
||||
```json
|
||||
mkdir nestedIotEdgeTutorial
|
||||
cd ~/nestedIotEdgeTutorial
|
||||
wget -O iotedge_config.tar "https://github.com/Azure-Samples/iotedge_config_cli/releases/download/latest/iotedge_config_cli.tar.gz"
|
||||
tar -xvf iotedge_config.tar
|
||||
```
|
||||
|
||||
This will create the iotedge_config_cli_release folder in your tutorial directory. The template file used to create your device hierarchy is the iotedge_config.yaml file found in ~/nestedIotEdgeTutorial/iotedge_config_cli_release/templates/tutorial. In the same directory, there're two deployment manifests for top and lower level deploymentTopLayer.json and deploymentLowerLayer.json files. Refer the #4 below on how to prepare them.
|
||||
|
||||
3. Edit iotedge_config.yaml with your information. This include the iothub_hostname, iot_name, deployment template file for both top layer and child as well as the credentials used to pull the image from upstream. Please refer [Quickstart: Deploy a connected registry to an IoT Edge device](quickstart-deploy-connected-registry-iot-edge-cli.md) if you are not familar how to create a client token. And you also make sure the client token get the permissions to pull all the required images. Below is a sample config.
|
||||
|
||||
```json
|
||||
config_version: "1.0"
|
||||
|
||||
iothub:
|
||||
iothub_hostname: myiothub.azure-devices.net
|
||||
iothub_name: myiothub
|
||||
## Authentication method used by IoT Edge devices: symmetric_key or x509_certificate
|
||||
authentication_method: symmetric_key
|
||||
|
||||
## Root certificate used to generate device CA certificates. Optional. If not provided a self-signed CA will be generated
|
||||
# certificates:
|
||||
# root_ca_cert_path: ""
|
||||
# root_ca_cert_key_path: ""
|
||||
|
||||
## IoT Edge configuration template to use
|
||||
configuration:
|
||||
template_config_path: "./templates/tutorial/device_config.toml"
|
||||
default_edge_agent: "$upstream:8000/azureiotedge-agent:20210609.5"
|
||||
|
||||
## Hierarchy of IoT Edge devices to create
|
||||
edgedevices:
|
||||
device_id: top-layerx
|
||||
edge_agent: "mycontainerregistry001.azurecr.io/azureiotedge-agent:20210609.5" ## Optional. If not provided, default_edge_agent will be used
|
||||
deployment: "./templates/tutorial/deploymentTopLayer.json" ## Optional. If provided, the given deployment file will be applied to the newly created device
|
||||
# hostname: "FQDN or IP" ## Optional. If provided, install.sh will not prompt user for this value nor the parent_hostname value
|
||||
container_auth: // The token used to pull the image from cloud registry
|
||||
serveraddress: "mycontainerregistry001.azurecr.io"
|
||||
username: "crimagepulltokentop"
|
||||
password: "HwBU+ZhB+X9AOmeAq6ZG2G/y2QD=8sfT"
|
||||
child:
|
||||
- device_id: lower-layerx
|
||||
deployment: "./templates/tutorial/deploymentLowerLayer.json" ## Optional. If provided, the given deployment file will be applied to the newly created device
|
||||
# hostname: "FQDN or IP" ## Optional. If provided, install.sh will not prompt user for this value nor the parent_hostname value
|
||||
container_auth: //The token used to pull the image from parent connected registry
|
||||
serveraddress: "$upstream:8000"
|
||||
username: "crimagepulltokenlower"
|
||||
password: "$$$0meCoMPL3xP4$$W0rd001!@#$$"
|
||||
```
|
||||
|
||||
|
||||
4. Prepare the top level and lower level deployment files (deploymentTopLayer.json and deploymentLowerLayer.json).
|
||||
|
||||
The top level deployment file is the same as the one you used to set up a connected registry on a IoT Edge device. Refer [Quickstart: Deploy a connected registry to an IoT Edge device](quickstart-deploy-connected-registry-iot-edge-cli.md). Make sure you do have API proxy module deployed on top layer and open the port `8000`, `5671`, `8883`.
|
||||
|
||||
For the lower level deployment file, please refer the above section 'Configure a deployment manifest for the nested IoT Edge' about the difference to the top level deployment file. Overall, the lowever level deployment file is similar as the top level deployment file. The differences are:
|
||||
|
||||
- It need pull all the images required from top level connected registry instead of from cloud registry or MCR.
|
||||
When you set up the top level connected registry, you need make sure it will sync up all the IoT agent, hub and connected registry images locally (azureiotedge-agent, azureiotedge-hub, connected-registry). The lower level IoT device need pull these images from the top level connected registry.
|
||||
- It need configure the parent gateway endpoint with the top level connected registry IP or FQDN instead of cloud registry.
|
||||
|
||||
5. Install in the top and lower level devices.
|
||||
Navigate to your iotedge_config_cli_releae directory and run the tool to create your hierarchy of IoT Edge devices.
|
||||
```json
|
||||
cd ~/nestedIotEdgeTutorial/iotedge_config_cli_release
|
||||
./iotedge_config --config ~/nestedIotEdgeTutorial/iotedge_config_cli_release/templates/tutorial/iotedge_config.yaml --output ~/nestedIotEdgeTutorial/iotedge_config_cli_release/outputs -f
|
||||
```
|
||||
|
||||
With the --output flag, the toos creates the device certificates, certificate bundles, and a log file in a directory of your choice. With the -f flag set, the tool will automatically look for existing IoT Edge devices in your IoT Hub and remove them, to avoid errors and keep your hub clean.
|
||||
|
||||
Copy the generated top-layer.zip and lower-layer.zip in above steps to the corresponding top and lower vms using scp。
|
||||
|
||||
```json
|
||||
scp <PATH_TO_CONFIGURATION_BUNDLE> <USER>@<VM_IP_OR_FQDN>:~
|
||||
```
|
||||
|
||||
Go to each device, unzip the configuration bundle. You'll need to install zip first.
|
||||
```json
|
||||
sudo apt install zip
|
||||
unzip ~/<PATH_TO_CONFIGURATION_BUNDLE>/<CONFIGURATION_BUNDLE>.zip (unzip top-layer.zip)
|
||||
```
|
||||
|
||||
Unzip the installation files and run ./install.sh, input the ip and host name. All are done for top layer device deployment. Run iotedge list to double check if all modules are running well.
|
||||
|
||||
Repeat the same steps in lower level device. Unzip files and run ./install.sh. Input the ip, host name and parent hostname.
|
||||
All are done for lower layer deployment. Run iotedge list to double check if all modules are running well.
|
||||
|
||||
If there're any problems e.g. invalid deployment manifest. You need manually redeploy the modules. Refer the next session on how to make a deployment manually on top or lower device.
|
||||
|
||||
## Manully Deploy the connected registry module on IoT Edge
|
||||
|
||||
The following step might be covered during nested iot setup after you run install.sh on top and lower level devices. However, it is also possible the previous deployment doesn't success and you can use the following way to redeploy it.
|
||||
|
||||
Use the following command to deploy the connected registry module on the IoT Edge device:
|
||||
|
||||
```azurecli
|
||||
az iot edge set-modules \
|
||||
--device-id [device id] \
|
||||
--hub-name [hub name] \
|
||||
--content [file path]
|
||||
```
|
||||
|
||||
For more details you can refer to the [Deploy Azure IoT Edge modules with Azure CLI](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-deploy-modules-cli?view=iotedge-2020-11) article.
|
||||
|
||||
To check the status of the connected registry, use the following CLI command:
|
||||
|
||||
```azurecli
|
||||
az acr connected-registry show \
|
||||
--registry mycontainerregistry001 \
|
||||
--name myconnectedmirror \
|
||||
--output table
|
||||
```
|
||||
|
||||
You may need to a wait few minutes until the deployment of the connected registry completes.
|
||||
|
||||
Successful response from the command will include the following:
|
||||
|
||||
```azurecli
|
||||
connectionState: Online
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
In this quickstart, you learned how to deploy a connected registry to an IoT Edge device. Continue to the next guide to learn how to pull images from the newly deployed connected registry.
|
||||
|
||||
> [Quickstart: Pull images from a connected registry][quickstart-pull-images-from-connected-registry]
|
||||
|
||||
<!-- LINKS - internal -->
|
||||
[az-acr-connected-registry-install]: /cli/azure/acr#az-acr-connected-registry-install
|
||||
[az-acr-import]: /cli/azure/acr#az-acr-import
|
||||
[az-acr-token-credential-generate]: /cli/azure/acr/credential#az-acr-token-credential-generate
|
||||
[container-registry-intro]: container-registry-intro.md
|
||||
[quickstart-pull-images-from-connected-registry]: quickstart-pull-images-from-connected-registry.md
|
||||
[quickstart-connected-registry-cli]: quickstart-connected-registry-cli.md
|
||||
|
|
@ -13,8 +13,6 @@ This article helps you troubleshoot problems you might encounter when setting up
|
|||
|
||||
## Symptoms
|
||||
|
||||
May include one or more of the following:
|
||||
|
||||
* Unable to push or pull images to or from the connected registry. Client error is `Error response from daemon: Get https://<connected-registry-login-server-ip-or-dns>/v2/: http: server gave HTTP response to HTTPS client`
|
||||
|
||||
## Causes
|
||||
|
|
@ -26,3 +24,88 @@ May include one or more of the following:
|
|||
### Configure Docker daemon to access insecure registry
|
||||
|
||||
The access the connected registry via HTTP, you must configure the client Docker daemon to allow access to insecure registries. The steps are described in [Test an insecure registry](https://docs.docker.com/registry/insecure/) article on Docker's web site.
|
||||
|
||||
## Symptoms
|
||||
|
||||
* Unable to pull an image from the connected registry. Client error is
|
||||
`Error response from daemon: manifest for <connected-registry-login-server-ip-or-dns>/<repository-name>:<tag> not found: manifest unknown: manifest unknown`
|
||||
|
||||
## Causes
|
||||
|
||||
* The connected registry is not configured to sync this repository from the Azure Container Registry.
|
||||
|
||||
## Potential solutions
|
||||
|
||||
### Configure the connected registry to sync the repository
|
||||
|
||||
In order to access this image, you must update the connected registry configuration to sync the repository. From the Azure CLI run
|
||||
`az acr connected-registry repo -r <ACR-name> -n <connected-registry-name> --add <repository-name>`
|
||||
|
||||
Wait a few minutes for the connected registry to sync the repository and try pulling the image again.
|
||||
|
||||
## Symptoms
|
||||
|
||||
* Unable to push or pull images to or from the connected registry. Client error is
|
||||
`Error response from daemon: pull access denied for <connected-registry-login-server-ip-or-dns>/<repository-name>, repository does not exist or may require 'docker login': denied: Insufficient scopes to perform the operation`
|
||||
|
||||
## Causes
|
||||
|
||||
* The repository is synced to the connected registry, but the client token used for `docker login` does not have access.
|
||||
|
||||
## Potential solutions
|
||||
|
||||
### Assign permissions to the connected registry client token
|
||||
|
||||
To update the permissions of the client token, you must update the corresponding scope map. To view the scope map resource ID associated with a token, run the following from the Azure CLI:
|
||||
|
||||
`az acr token show -r <ACR-name> -n <client-token-name> -o tsv --query scopeMapId`
|
||||
|
||||
#### Pull permissions
|
||||
|
||||
To give the client token pull permissions to the repository, run the following from the Azure CLI:
|
||||
|
||||
```
|
||||
az acr scope-map update \
|
||||
--name <scope-map-name> \
|
||||
--registry <ACR-name> \
|
||||
--add-repository <repository-name> content/read
|
||||
```
|
||||
|
||||
#### Push permissions
|
||||
|
||||
If the connected registry is in Registry mode, the client may need push access. To give the client token push permissions to the repository, run the following from the Azure CLI:
|
||||
|
||||
```
|
||||
az acr scope-map update \
|
||||
--name <scope-map-name> \
|
||||
--registry <ACR-name> \
|
||||
--add-repository <repository-name> content/read content/write
|
||||
```
|
||||
|
||||
Wait a few minutes for the updated client token permissions to sync to the connected registry.
|
||||
|
||||
> [!TIP]
|
||||
> After updating the permissions of the client token, you may want to generate new passwords. Run `az acr token credential generate` from the Azure CLI to refresh your client token passwords. Allow a few minutes for the credentials to sync to the connected registry. Login using your new credentials with `docker login`.
|
||||
|
||||
For more information on ACR token management please reference [Create a token with repository-scoped permissions](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions]).
|
||||
|
||||
## Symptoms
|
||||
|
||||
* Unable to push an image to the connected registry. Client error is
|
||||
`denied: This operation is not allowed on this registry.`
|
||||
|
||||
## Causes
|
||||
|
||||
* Images can only be pushed to a connected registry in `Registry` mode. If the connected registry is in `Mirror` mode then only readonly operations are allowed, such as `docker pull`.
|
||||
|
||||
## Potential solutions
|
||||
|
||||
### Create a new connected registry in Registry mode
|
||||
|
||||
Once a connected registry is created, the mode cannot be changed. If you would like to push images to your connected registry, create a new resource in Registry mode. Ensure the client token linked to the new connected registry has push permissions to the synced repositories.
|
||||
|
||||
From the Azure CLI run
|
||||
|
||||
`az acr connected-registry create --registry <ACR-name> --name <connected-registry-name> --repository app/hello-world service/mycomponent --client-tokens <client-token-name>`
|
||||
|
||||
Deploy the connected registry. For an example on how to deploy a connected registry on IoT Edge, please reference [Quickstart - Deploy a connected registry to an IoT Edge device](./quickstart-deploy-connected-registry-iot-edge-cli.md). Once deployed, you can use the client token to login and push images to the connected registry. These images will be synced from the connected registry to the ACR.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
# Collecting Logs for Teleport on AKS
|
||||
This guide goes over how to collect logs for the teleportd daemon running in an AKS cluster. The steps in this guide have to be carried out by customers in order to collect log information for debugging purposes.
|
||||
|
||||
## Teleportd logs
|
||||
We can get teleportd logs from each node independently to verify that a teleport enabled image succesfully teleported. Because Teleportd is run as a daemon in the node, its logs are only available from journald in a node. To get these a user can either connect to their node which ran the specific pod being debugged (using ssh or lens) and run `journalctl -n all -u teleportd`. Alternatively you can collect logs by creating sidecar container on the corresponding nodes like we do. The sidecar mounts the filesystem of the nodepool and uses this to obtain journald logs. These are created using the following configuration:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: teleport-logs
|
||||
spec:
|
||||
containers:
|
||||
- name: log-reader
|
||||
image: busybox
|
||||
args: [/bin/sh, -c, '/bin/journalctl -n all -u teleportd -f']
|
||||
volumeMounts:
|
||||
- name: rootfs
|
||||
mountPath: /
|
||||
# Add if customer needs to specify node
|
||||
# nodeSelector:
|
||||
# teleport: "true"
|
||||
volumes:
|
||||
- name: rootfs
|
||||
hostPath:
|
||||
path: /
|
||||
type: Directory
|
||||
```
|
||||
|
||||
You can run a pod with the above configuration (make sure to edit the nodeSelector field to set the log collection to the specific node that needs its instance of teleportd to be debugged) and then get the logs from it by calling:
|
||||
`kubectl logs teleport-logs > ./teleport-daemon.log`
|
||||
|
||||
|
||||
## Other options
|
||||
### Kubernetes Events (Aside)
|
||||
If the affected pod was just ran (events have a short timespan) you can use the following to gather some extra information and even confirm the image teleported:
|
||||
|
||||
For event collection we are looking at two methods:
|
||||
- Running `kubectl describe pod <your pod name>`
|
||||
Teleportd events try to associate with the pod that first pulled a specific image within a node, nonetheless this can fail, in such a scenario events are not associated with a node but are still reported as general events and will still be visible when running kubectl get events. If everything goes rights the output of this command will include the teleport events, otherwise:
|
||||
|
||||
- Running `kubectl get events`
|
||||
In cases when teleportd fails to associate events with a pod or when multiple pods experienced issues, check all the kubectl get events, they are all sourced from the teleportd client and are marked as such, some will have the image and tag that was teleport or if it failed to teleport.
|
||||
|
||||
Events include overall failure information for teleportd but do not currently give information on individual layer failures. If an image took too long to teleport for example and the events still indicate success there could be individual layer mount failures, refer to the logs in that scenario.
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
#!/bin/bash
|
||||
#usage: edit-teleport-attribute.sh acr-name repo enable
|
||||
#usage: eg: edit-teleport-attribute.sh demo42 /demo42/hello-world 2.1 disable
|
||||
#usage: eg: edit-teleport-attribute.sh demo42 /demo42/hello-world 2.1 enable --debug
|
||||
# Assumes ACR_USER and ACR_PWD are set to valid ACRPULL role
|
||||
# Retrieve the ACR_PWD with the following command, if the Admin account is enabled
|
||||
# ACR_PWD="$(az acr credential show -n demo42t --query passwords[0].value -o tsv)"
|
||||
# NOTE: Repo scoped tokens will be coming online in November
|
||||
ACR_NAME=$1
|
||||
ACR_REPO=$2
|
||||
STATE=$3
|
||||
DEBUG=$4
|
||||
|
||||
# Troubleshooting
|
||||
if [[ $DEBUG = '--debug' ]]; then
|
||||
echo "Parameter Validation:"
|
||||
echo " ACR_USER: ${ACR_USER}"
|
||||
echo " ACR_PWD : ${ACR_PWD}"
|
||||
echo " ACR_NAME: ${ACR_NAME}"
|
||||
echo " ACR_REPO: ${ACR_REPO}"
|
||||
fi
|
||||
|
||||
echo "Getting Access Token"
|
||||
|
||||
ACR_ACCESS_TOKEN=$(curl -s -u ${ACR_USER}:${ACR_PWD} "https://${ACR_NAME}.azurecr.io/oauth2/token?service=${ACR_NAME}.azurecr.io&scope=repository:${ACR_REPO}:pull,push" | sed -e 's/[{}]/''/g' | awk -v RS=',"' -F: '/access_token/ {print $2}' | sed 's/^.//;s/.$//')
|
||||
|
||||
if [[ $ACR_ACCESS_TOKEN == '' ]]; then
|
||||
echo "Could not get access token, make sure credentials are accurate and have pull access"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ $DEBUG == '--debug' ]]; then
|
||||
echo " ACR_ACCESS_TOKEN: ${ACR_ACCESS_TOKEN}"
|
||||
fi
|
||||
|
||||
SET_STATE=""
|
||||
|
||||
if [[ $STATE == 'enable' ]]; then
|
||||
SET_STATE="{\"teleportEnabled\": true }"
|
||||
fi
|
||||
|
||||
if [[ $STATE == 'disable' ]]; then
|
||||
SET_STATE="{\"teleportEnabled\": false }"
|
||||
fi
|
||||
|
||||
if [[ $DEBUG == '--debug' ]]; then
|
||||
echo " SET_STATE: ${SET_STATE}"
|
||||
fi
|
||||
|
||||
echo "Sendng Patch Request for $ACR_REPO"
|
||||
|
||||
RESULT=$(curl -s -S \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer ${ACR_ACCESS_TOKEN}" \
|
||||
--request PATCH \
|
||||
--data "${SET_STATE}" \
|
||||
https://$ACR_NAME.azurecr.io/acr/v1/$ACR_REPO)
|
||||
|
||||
echo " RESULT: ${RESULT}"
|
||||
|
||||
|
||||
|
|
@ -74,7 +74,7 @@
|
|||
<dependency>
|
||||
<groupId>org.apache.httpcomponents</groupId>
|
||||
<artifactId>httpclient</artifactId>
|
||||
<version>4.5.3</version>
|
||||
<version>4.5.13</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</project>
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче