|
| 1 | +--- |
| 2 | +title: Quickstart - Send Azure Container Registry events to Event Grid |
| 3 | +description: In this quickstart, you enable Event Grid events for your container registry, then send container image push and delete events to a sample application. |
| 4 | +services: container-registry |
| 5 | +author: mmacy |
| 6 | +manager: jeconnoc |
| 7 | + |
| 8 | +ms.service: container-registry |
| 9 | +ms.topic: article |
| 10 | +ms.date: 08/17/2018 |
| 11 | +ms.author: marsma |
| 12 | +# Customer intent: As a container registry owner, I want to send events to Event Grid |
| 13 | +# when container images are pushed to or deleted from my container registry so that |
| 14 | +# downstream applications can react to those events. |
| 15 | +--- |
| 16 | + |
| 17 | +# Quickstart: Send container registry events to Event Grid |
| 18 | + |
| 19 | +Azure Event Grid is a fully managed event routing service that provides uniform event consumption using a publish-subscribe model. In this quickstart, you use the Azure CLI to create a container registry, subscribe to registry events, then deploy a sample web application to receive the events. Finally, you trigger container image `push` and `delete` events and view the event payload in the sample application. |
| 20 | + |
| 21 | +After you complete the steps in this article, events sent from your container registry to Event Grid appear in the sample web app: |
| 22 | + |
| 23 | +![Web browser rendering the sample web application with three received events][sample-app-01] |
| 24 | + |
| 25 | +If you don't have an Azure subscription, create a [free account][azure-account] before you begin. |
| 26 | + |
| 27 | +[!INCLUDE [cloud-shell-try-it.md](../../includes/cloud-shell-try-it.md)] |
| 28 | + |
| 29 | +The Azure CLI commands in this article are formatted for the **Bash** shell. If you're using a different shell like PowerShell or Command Prompt, you may need to adjust line continuation characters or variable assignment lines accordingly. This article uses variables to minimize the amount of command editing required. |
| 30 | + |
| 31 | +## Create a resource group |
| 32 | + |
| 33 | +An Azure resource group is a logical container in which you deploy and manage your Azure resources. The following [az group create][az-group-create] command creates a resource group named *myResourceGroup* in the *eastus* region. If you want to use a different name for your resource group, set `RESOURCE_GROUP_NAME` to a different value. |
| 34 | + |
| 35 | +```azurecli-interactive |
| 36 | +RESOURCE_GROUP_NAME=myResourceGroup |
| 37 | +
|
| 38 | +az group create --name $RESOURCE_GROUP_NAME --location eastus |
| 39 | +``` |
| 40 | + |
| 41 | +## Create a container registry |
| 42 | + |
| 43 | +Next, deploy a container registry into the resource group with the following commands. Before you run the [az acr create][az-acr-create] command, set `ACR_NAME` to a name for your registry. The name must be unique within Azure, and is restricted to 5-50 alphanumeric characters. |
| 44 | + |
| 45 | +```azurecli-interactive |
| 46 | +ACR_NAME=<acrName> |
| 47 | +
|
| 48 | +az acr create --resource-group $RESOURCE_GROUP_NAME --name $ACR_NAME --sku Basic |
| 49 | +``` |
| 50 | + |
| 51 | +Once the registry has been created, the Azure CLI returns output similar to the following: |
| 52 | + |
| 53 | +```json |
| 54 | +{ |
| 55 | + "adminUserEnabled": false, |
| 56 | + "creationDate": "2018-08-16T20:02:46.569509+00:00", |
| 57 | + "id": "/subscriptions/<Subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/myregistry", |
| 58 | + "location": "eastus", |
| 59 | + "loginServer": "myregistry.azurecr.io", |
| 60 | + "name": "myregistry", |
| 61 | + "provisioningState": "Succeeded", |
| 62 | + "resourceGroup": "myResourceGroup", |
| 63 | + "sku": { |
| 64 | + "name": "Basic", |
| 65 | + "tier": "Basic" |
| 66 | + }, |
| 67 | + "status": null, |
| 68 | + "storageAccount": null, |
| 69 | + "tags": {}, |
| 70 | + "type": "Microsoft.ContainerRegistry/registries" |
| 71 | +} |
| 72 | + |
| 73 | +``` |
| 74 | + |
| 75 | +## Create an event endpoint |
| 76 | + |
| 77 | +In this section, you use a Resource Manager template located in a GitHub repository to deploy a pre-built sample web application to Azure App Service. Later, you subscribe to your registry's Event Grid events and specify this app as the endpoint to which the events are sent. |
| 78 | + |
| 79 | +To deploy the sample app, set `SITE_NAME` to a unique name for your web app, and execute the following commands. The site name must be unique within Azure because it forms part of the fully qualified domain name (FQDN) of the web app. In a later section, you navigate to the app's FQDN in a web browser to view your registry's events. |
| 80 | + |
| 81 | +```azurecli-interactive |
| 82 | +SITE_NAME=<your-site-name> |
| 83 | +
|
| 84 | +az group deployment create \ |
| 85 | + --resource-group $RESOURCE_GROUP_NAME \ |
| 86 | + --template-uri "https://raw.githubusercontent.com/dbarkol/azure-event-grid-viewer/master/azuredeploy.json" \ |
| 87 | + --parameters siteName=$SITE_NAME hostingPlanName=$SITE_NAME-plan |
| 88 | +``` |
| 89 | + |
| 90 | +Once the deployment has succeeded (it might take a few minutes), open a browser and navigate to your web app to make sure it's running: |
| 91 | + |
| 92 | +`http://<your-site-name>.azurewebsites.net` |
| 93 | + |
| 94 | +You should see the sample app rendered with no event messages displayed: |
| 95 | + |
| 96 | +![Web browser showing sample web app with no events displayed][sample-app-02] |
| 97 | + |
| 98 | +[!INCLUDE [event-grid-register-provider-cli.md](../../includes/event-grid-register-provider-cli.md)] |
| 99 | + |
| 100 | +## Subscribe to registry events |
| 101 | + |
| 102 | +In Event Grid, you subscribe to a *topic* to tell it which events you want to track, and where to send them. The following [az eventgrid event-subscription create][az-eventgrid-event-subscription-create] command subscribes to the container registry you created, and specifies your web app's URL as the endpoint to which it should send events. The environment variables you populated in earlier sections are reused here, so no edits are required. |
| 103 | + |
| 104 | +```azurecli-interactive |
| 105 | +ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv) |
| 106 | +APP_ENDPOINT=https://$SITE_NAME.azurewebsites.net/api/updates |
| 107 | +
|
| 108 | +az eventgrid event-subscription create \ |
| 109 | + --name event-sub-acr \ |
| 110 | + --resource-id $ACR_REGISTRY_ID \ |
| 111 | + --endpoint $APP_ENDPOINT |
| 112 | +``` |
| 113 | + |
| 114 | +When the subscription is completed, you should output similar to the following: |
| 115 | + |
| 116 | +```JSON |
| 117 | +{ |
| 118 | + "destination": { |
| 119 | + "endpointBaseUrl": "https://eventgridviewer.azurewebsites.net/api/updates", |
| 120 | + "endpointType": "WebHook", |
| 121 | + "endpointUrl": null |
| 122 | + }, |
| 123 | + "filter": { |
| 124 | + "includedEventTypes": [ |
| 125 | + "All" |
| 126 | + ], |
| 127 | + "isSubjectCaseSensitive": null, |
| 128 | + "subjectBeginsWith": "", |
| 129 | + "subjectEndsWith": "" |
| 130 | + }, |
| 131 | + "id": "/subscriptions/<Subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/myregistry/providers/Microsoft.EventGrid/eventSubscriptions/event-sub-acr", |
| 132 | + "labels": null, |
| 133 | + "name": "event-sub-acr", |
| 134 | + "provisioningState": "Succeeded", |
| 135 | + "resourceGroup": "myResourceGroup", |
| 136 | + "topic": "/subscriptions/<Subscription ID>/resourceGroups/myresourcegroup/providers/microsoft.containerregistry/registries/myregistry", |
| 137 | + "type": "Microsoft.EventGrid/eventSubscriptions" |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +## Trigger registry events |
| 142 | + |
| 143 | +Now that the sample app is up and running and you've subscribed to your registry with Event Grid, you're ready to generate some events. In this section, you use ACR Build to build and push a container image to your registry. ACR Build is a feature of Azure Container Registry that allows you to build container images in the cloud, without needing the Docker Engine installed on your local machine. |
| 144 | + |
| 145 | +### Build and push image |
| 146 | + |
| 147 | +Execute the following Azure CLI command to build a container image from the contents of a GitHub repository. By default, ACR Build automatically pushes a successfully built image to your registry, which generates the `ImagePushed` event. |
| 148 | + |
| 149 | +```azurecli-interactive |
| 150 | +az acr build --registry $ACR_NAME --image myimage:v1 https://github.com/Azure-Samples/acr-build-helloworld-node.git |
| 151 | +``` |
| 152 | + |
| 153 | +You should see output similar to the following while ACR Build builds and then pushes your image. The following sample output has been truncated for brevity. |
| 154 | + |
| 155 | +```console |
| 156 | +$ az acr build -r $ACR_NAME --image myimage:v1 https://github.com/Azure-Samples/acr-build-helloworld-node.git |
| 157 | +Sending build context to ACR... |
| 158 | +Queued a build with build ID: aa2 |
| 159 | +Waiting for build agent... |
| 160 | +2018/08/16 22:19:38 Using acb_vol_27a2afa6-27dc-4ae4-9e52-6d6c8b7455b2 as the home volume |
| 161 | +2018/08/16 22:19:38 Setting up Docker configuration... |
| 162 | +2018/08/16 22:19:39 Successfully set up Docker configuration |
| 163 | +2018/08/16 22:19:39 Logging in to registry: myregistry.azurecr.io |
| 164 | +2018/08/16 22:19:55 Successfully logged in |
| 165 | +Sending build context to Docker daemon 94.72kB |
| 166 | +Step 1/5 : FROM node:9-alpine |
| 167 | +... |
| 168 | +``` |
| 169 | + |
| 170 | +To verify that the built image is in your registry, execute the following command to view the tags in the "myimage" repository: |
| 171 | + |
| 172 | +```azurecli-interactive |
| 173 | +az acr repository show-tags --name $ACR_NAME --repository myimage |
| 174 | +``` |
| 175 | + |
| 176 | +The "v1" tag of the image you built should appear in the output, similar to the following: |
| 177 | + |
| 178 | +```console |
| 179 | +$ az acr repository show-tags --name $ACR_NAME --repository myimage |
| 180 | +[ |
| 181 | + "v1" |
| 182 | +] |
| 183 | +``` |
| 184 | + |
| 185 | +### Delete the image |
| 186 | + |
| 187 | +Now, generate an `ImageDeleted` event by deleting the image with the [az acr repository delete][az-acr-repository-delete] command: |
| 188 | + |
| 189 | +```azurecli-interactive |
| 190 | +az acr repository delete --name $ACR_NAME --image myimage:v1 |
| 191 | +``` |
| 192 | + |
| 193 | +You should see output similar to the following, asking for confirmation to delete the manifest and associated images: |
| 194 | + |
| 195 | +```console |
| 196 | +$ az acr repository delete --name $ACR_NAME --image myimage:v1 |
| 197 | +This operation will delete the manifest 'sha256:f15fa9d0a69081ba93eee308b0e475a54fac9c682196721e294b2bc20ab23a1b' and all the following images: 'myimage:v1'. |
| 198 | +Are you sure you want to continue? (y/n): y |
| 199 | +``` |
| 200 | + |
| 201 | +## View registry events |
| 202 | + |
| 203 | +You've now pushed an image to your registry and then deleted it. Navigate to your Event Grid Viewer web app, and you should see both `ImageDeleted` and `ImagePushed` events. You might also see a subscription validation event generated by executing the command in the [Subscribe to registry events](#subscribe-to-registry-events) section. |
| 204 | + |
| 205 | +The following screenshot shows the sample app with the three events, and the `ImageDeleted` event is expanded to show its details. |
| 206 | + |
| 207 | +![Web browser showing the sample app with ImagePushed and ImageDeleted events][sample-app-03] |
| 208 | + |
| 209 | +Congratulations! If you see the `ImagePushed` and `ImageDeleted` events, your registry is sending events to Event Grid, and Event Grid is forwarding those events to your web app endpoint. |
| 210 | + |
| 211 | +## Clean up resources |
| 212 | + |
| 213 | +Once you're done with the resources you created in this quickstart, you can delete them all with the following Azure CLI command. When you delete a resource group, all of the resources it contains are permanently deleted. |
| 214 | + |
| 215 | +**WARNING**: This operation is irreversible. Be sure you no longer need any of the resources in the group before running the command. |
| 216 | + |
| 217 | +```azurecli-interactive |
| 218 | +az group delete --name $RESOURCE_GROUP_NAME |
| 219 | +``` |
| 220 | + |
| 221 | +## Event Grid event schema |
| 222 | + |
| 223 | +You can find the Azure Container Registry event message schema reference in the Event Grid documentation: |
| 224 | + |
| 225 | +[Azure Event Grid event schema for Container Registry](../event-grid/event-schema-container-registry.md) |
| 226 | + |
| 227 | +## Next steps |
| 228 | + |
| 229 | +In this quickstart, you deployed a container registry, built an image with ACR Build, deleted it, and have consumed your registry's events from Event Grid with a sample application. Next, move on to the ACR Build tutorial to learn more about building container images in the cloud, including automated builds on base image update: |
| 230 | + |
| 231 | +> [!div class="nextstepaction"] |
| 232 | +> [Build container images in the cloud with ACR Build](container-registry-tutorial-quick-build.md) |
| 233 | +
|
| 234 | +<!-- IMAGES --> |
| 235 | +[sample-app-01]: ./media/container-registry-event-grid-quickstart/sample-app-01.png |
| 236 | +[sample-app-02]: ./media/container-registry-event-grid-quickstart/sample-app-02-no-events.png |
| 237 | +[sample-app-03]: ./media/container-registry-event-grid-quickstart/sample-app-03-with-events.png |
| 238 | + |
| 239 | +<!-- LINKS - External --> |
| 240 | +[azure-account]: https://azure.microsoft.com/free/?WT.mc_id=A261C142F |
| 241 | +[sample-app]: https://github.com/dbarkol/azure-event-grid-viewer |
| 242 | + |
| 243 | +<!-- LINKS - Internal --> |
| 244 | +[az-acr-create]: /cli/azure/acr/repository#az-acr-create |
| 245 | +[az-acr-repository-delete]: /cli/azure/acr/repository#az-acr-repository-delete |
| 246 | +[az-eventgrid-event-subscription-create]: /cli/azure/eventgrid/event-subscription#az-eventgrid-event-subscription-create |
| 247 | +[az-group-create]: /cli/azure/group#az-group-create |
0 commit comments