Skip to content

Commit 4707230

Browse files
dlepowdlepow
committed
[ACI] GitHub action
1 parent 2c6badd commit 4707230

File tree

4 files changed

+294
-0
lines changed

4 files changed

+294
-0
lines changed

‎articles/container-instances/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@
5959
href: container-instances-vnet.md
6060
- name: Deploy from Azure Container Registry
6161
href: container-instances-using-azure-container-registry.md
62+
- name: Deploy with GitHub Actions (preview)
63+
href: container-instances-github-action.md
6264
- name: Encrypt deployment data
6365
href: container-instances-encrypt-data.md
6466
- name: Deploy on dedicated hosts

‎articles/container-instances/container-instances-github-action.md

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
---
2+
title: Trigger container group by GitHub action
3+
description: Configure a GitHub action that automates steps to build, push, and deploy a container image to Azure Container Instances
4+
ms.topic: article
5+
ms.date: 03/17/2020
6+
ms.custom:
7+
---
8+
9+
# Configure a GitHub action to create a container group
10+
11+
[GitHub Actions](https://help.github.com/actions/getting-started-with-github-actions/about-github-actions) is a suite of features in GitHub to automate your software development workflows in the same place you store code and collaborate on pull requests and issues.
12+
13+
Use GitHub actions to automate deployment of a container image to Azure Container Instances. This article shows you how to set up a workflow in a GitHub repo triggered by push of a code commit that performs the following actions:
14+
15+
* Build an image from a Dockerfile
16+
* Push the image to an Azure container registry
17+
* Deploy the container image to Azure Container Instances
18+
19+
This article shows two methods to set up the workflow:
20+
21+
* Configure a workflow in a GitHub repo that uses the [Deploy to Azure Container Instances](https://github.com/azure/aci-deploy-action) action
22+
* Use the `az container app up` command in the [Deploy to Azure](https://github.com/Azure/deploy-to-azure-cli-extension) extension in the Azure CLI. This command streamlines creation of the GitHub workflow and deployment steps
23+
24+
> [!IMPORTANT]
25+
> The GitHub action for Azure Container Instances is currently in preview. Previews are made available to you on the condition that you agree to the [supplemental terms of use][terms-of-use]. Some aspects of this feature may change prior to general availability (GA).
26+
27+
## Prerequisites
28+
29+
* **GitHub account** - Create an account on https://github.com if you don't already have one.
30+
* **Azure CLI** - You can use the Azure Cloud Shell or a local installation of the Azure CLI to complete the Azure CLI steps. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].
31+
* **Azure container registry** - If you don't have one, create an Azure container registry in the Basic tier using the [Azure CLI](../container-registry/container-registry-get-started-azure-cli.md), [Azure portal](../container-registry/container-registry-get-started-portal.md), or other methods. Take note of the resource group used for the deployment, which is used for the GitHub workflow.
32+
33+
## Workflow setup
34+
35+
### Fork sample repo
36+
37+
* For the examples in this article, use GitHub to fork the following repository: https://github.com/Azure-Samples/acr-build-helloworld-node
38+
39+
This repo contains a Dockerfile to create a container image of a small web app.
40+
41+
![Screenshot of the Fork button (highlighted) in GitHub](../container-registry/media/container-registry-tutorial-quick-build/quick-build-01-fork.png)
42+
43+
* Ensure Actions is enabled for your repository. Navigate to your forked repository and select **Settings** > **Actions**. In **Actions permissions**, ensure that **Enable local and third party Actions for this repository** is selected.
44+
45+
## Configure GitHub workflow
46+
47+
### Create service principal for Azure authentication
48+
49+
In the GitHub workflow, you need to supply Azure credentials to authenticate to the Azure CLI. The following example creates a service principal with the Contributor role scoped to the resource group for your container registry.
50+
51+
First, get the resource ID of your resource group. Substitute the name of your group in the following [az group show][az-acr-show] command:
52+
53+
```azurecli
54+
groupId=$(az group show \
55+
--name <registry-name> \
56+
--query id --output tsv)
57+
```
58+
59+
Use [az ad sp create-for-rbac][az-ad-sp-create-for-rbac] to create the service principal:
60+
61+
```azurecli
62+
az ad sp create-for-rbac \
63+
--scope $groupId \
64+
--role Contributor \
65+
--sdk-auth
66+
```
67+
68+
Output is similar to:
69+
70+
```json
71+
{
72+
"clientId": "xxxx6ddc-xxxx-xxxx-xxx-ef78a99dxxxx",
73+
"clientSecret": "xxxx79dc-xxxx-xxxx-xxxx-aaaaaec5xxxx",
74+
"subscriptionId": "xxxx251c-xxxx-xxxx-xxxx-bf99a306xxxx",
75+
"tenantId": "xxxx88bf-xxxx-xxxx-xxxx-2d7cd011xxxx",
76+
"activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
77+
"resourceManagerEndpointUrl": "https://management.azure.com/",
78+
"activeDirectoryGraphResourceId": "https://graph.windows.net/",
79+
"sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
80+
"galleryEndpointUrl": "https://gallery.azure.com/",
81+
"managementEndpointUrl": "https://management.core.windows.net/"
82+
}
83+
```
84+
85+
Save the JSON output because it is used in a later step. Also, take note of the `clientID`, which you need to update the service principal in the next section.
86+
87+
### Update service principal for registry authentication
88+
89+
Update the Azure service principal credentials to allow push and pull permissions on your container registry. This step allows you to use the service principal to [authenticate with your container registry](../container-registry/container-registry-auth-service-principal.md).
90+
91+
Get the resource ID of your container registry. Substitute the name of your registry in the following [az acr show][az-acr-show] command:
92+
93+
```azurecli
94+
registryId=$(az acr show \
95+
--name <registry-name> \
96+
--query id --output tsv)
97+
```
98+
99+
Use [az role assignment create][az-role-assignment-create] to assign the AcrPush role, which gives push and pull access to the registry. Substitute the client ID of your service principal:
100+
101+
```azurecli
102+
az role assignment create \
103+
--assignee <ClientId> \
104+
--scope $registryId \
105+
--role AcrPush
106+
```
107+
108+
### Save credentials to GitHub repo
109+
110+
In the GitHub UI, navigate to your forked repository and select **Settings** > **Secrets**. Select **Add a new secret** to add the following secrets:
111+
112+
|Secret |Value |
113+
|---------|---------|
114+
|`AZURE_CREDENTIALS` | The entire JSON output from the service principal creation |
115+
|`REGISTRY_LOGIN_SERVER` | The login server name of your registry (all lowercase). Example: *myregistry.azure.cr.io* |
116+
|`REGISTRY_USERNAME` | The `clientId` from the JSON output from the service principal creation |
117+
|`REGISTRY_PASSWORD` | The `clientSecret` from the JSON output from the service principal creation |
118+
| `RESOURCE_GROUP` | Name | The name of the resource group you used to scope the service principal |
119+
120+
### Create workflow file
121+
122+
1. In the GitHub UI, select **Actions** > **New workflow**.
123+
1. Select **Set up a workflow yourself**.
124+
1. In **Edit new file**, paste the following YAML contents to overwrite the sample code. Accept the default filename `main.yml`, or provide a filename you choose.
125+
1. Select **Start commit**, optionally provide short and extended descriptions of your commit, and select **Commit new file**.
126+
127+
```yml
128+
on: [push]
129+
name: Linux_Container_Workflow
130+
131+
jobs:
132+
build-and-deploy:
133+
runs-on: ubuntu-latest
134+
steps:
135+
# checkout the repo
136+
- name: 'Checkout GitHub Action'
137+
uses: actions/checkout@master
138+
139+
- name: 'Login via Azure CLI'
140+
uses: azure/login@v1
141+
with:
142+
creds: ${{ secrets.AZURE_CREDENTIALS }}
143+
144+
- name: 'Build and push image'
145+
uses: azure/docker-login@v1
146+
with:
147+
login-server: ${{ secrets.REGISTRY_LOGIN_SERVER }}
148+
username: ${{ secrets.REGISTRY_USERNAME }}
149+
password: ${{ secrets.REGISTRY_PASSWORD }}
150+
- run: |
151+
docker build . -t ${{ secrets.REGISTRY_LOGIN_SERVER }}/sampleapp:${{ github.sha }}
152+
docker push ${{ secrets.REGISTRY_LOGIN_SERVER }}/sampleapp:${{ github.sha }}
153+
154+
- name: 'Deploy to Azure Container Instances'
155+
uses: 'azure/aci-deploy-action@v1'
156+
with:
157+
resource-group: ${{ secrets.RESOURCE_GROUP }}
158+
dns-name-label: ${{ secrets.RESOURCE_GROUP }}${{ github.run_number }}
159+
image: ${{ secrets.REGISTRY_LOGIN_SERVER }}/sampleapp:${{ github.sha }}
160+
registry-login-server: ${{ secrets.REGISTRY_LOGIN_SERVER }}
161+
registry-username: ${{ secrets.REGISTRY_USERNAME }}
162+
registry-password: ${{ secrets.REGISTRY_PASSWORD }}
163+
name: aci-sampleapp
164+
location: 'west us'
165+
```
166+
167+
### Validate workflow
168+
169+
After you commit the workflow file, the workflow is triggered. To review workflow progress, navigate to **Actions** > **Workflows**. See [Managing a workflow run](https://help.github.com/actions/configuring-and-managing-workflows/managing-a-workflow-run) for information about viewing the status and results of each step in your workflow.
170+
171+
![View workflow progress](./media/container-instances-github-action/github-action-progress.png)
172+
173+
When the workflow completes, get information about the container instance named `aci-sampleapp` by running the [az container show][az-container-show] command. Substitute the name of your resource group:
174+
175+
```azurecli
176+
az container show \
177+
--resource-group <resource-group-name> \
178+
--name aci-sampleapp \
179+
--query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \
180+
--output table
181+
```
182+
183+
Output is similar to:
184+
185+
```console
186+
FQDN ProvisioningState
187+
--------------------------------- -------------------
188+
aci-action01.westus.azurecontainer.io Succeeded
189+
```
190+
191+
After the instance is provisioned, navigate to the container's FQDN in your browser to view the web app.
192+
193+
![Running web app in browser](./media/container-instances-github-action/github-action-container.png)
194+
195+
## Use the Azure CLI
196+
197+
Alternatively, use the [Deploy to Azure extension](https://github.com/Azure/deploy-to-azure-cli-extension) in the Azure CLI to configure the workflow. The `az container app up` command in the extension takes minimal input parameters from you and creates a GitHub workflow for you in your repository.
198+
199+
The workflow created by the Azure CLI is similar to the workflow you can [create manually using GitHub](#configure-github-workflow).
200+
201+
### Additional prerequisites
202+
203+
In addition to the [prerequisites](#prerequisites) and [workflow setup](#workflow-setup) for this scenario, you need to install the **Deploy to Azure extension** for the Azure CLI.
204+
205+
Run the [az extension add][az-extension-add] command to install the extension:
206+
207+
<TODO: Link to prod extension?>
208+
209+
```azurecli
210+
az extension add \
211+
--source https://github.com/Azure/deploy-to-azure-cli-extension/releases/download/20200311.2/deploy_to_azure-0.1.0-py2.py3-none-any.whl
212+
```
213+
214+
For information about finding, installing, and managing extensions, see [Use extensions with Azure CLI](/cli/azure/azure-cli-extensions-overview).
215+
216+
### Deploy to Azure Container Instances
217+
218+
To run the [az container app up][az-container-app-up] command, provide at minimum:
219+
220+
* The name of your Azure container registry, for example, *myrewgistry*
221+
* The URL to your GitHub repo, for example, `https://github.com/<your-GitHub-Id>/acr-build-helloworld-node`
222+
223+
Sample command:
224+
225+
```azurecli
226+
az container app up \
227+
--acr myregistry \
228+
--repository https://github.com/myID/acr-build-helloworld-node
229+
```
230+
231+
When prompted, provide your GitHub credentials. The command then creates a personal access token (PAT) to authenticate with your registry. The token has *repo* and *user* scopes on the repo. Alternatively, [create your own PAT](https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with those scopes and supply that when prompted.
232+
233+
The command creates:
234+
235+
* Service principal credentials for the workflow
236+
* Credentials to access the Azure container registry
237+
* A YAML file to define the GitHub workflow. By default the filename is `main.yml` but you can provide a different filename.
238+
239+
After you provide input to commit the workflow file to your repo, the workflow is triggered. Output is similar to:
240+
241+
```console
242+
[...]
243+
Checking in file github/workflows/main.yml in the Github repository myid/acr-build-helloworld-node
244+
Creating workflow...
245+
GitHub Action Workflow has been created - https://github.com/myid/acr-build-helloworld-node/runs/515192398
246+
GitHub workflow completed.
247+
Workflow succeeded
248+
Your app is deployed at: http://acr-build-helloworld-node.eastus.azurecontainer.io:8080/
249+
```
250+
251+
The workflow deploys an Azure container instance with the base name of your GitHub repo. In this case, the instance name is *acr-build-helloworld-node*. In your browser, you can browse to the link provided to view the running web app.
252+
253+
To view the workflow status and results of each step in the GitHub UI, see [Managing a workflow run](https://help.github.com/actions/configuring-and-managing-workflows/managing-a-workflow-run).
254+
255+
## Clean up resources
256+
257+
Stop the container instance with the [az container delete][az-container-delete] command:
258+
259+
```azurecli
260+
az container delete \
261+
--name <instance-name>
262+
--resource-group <resource-group-name>
263+
```
264+
265+
To delete the resource group and all the resources in it, run the [az group delete][az-group-delete] command:
266+
267+
```azurecli
268+
az group delete \
269+
--name <resource-group-name>
270+
```
271+
272+
## Next steps
273+
274+
Browse the [GitHub Marketplace](https://github.com/marketplace?type=actions) for more actions to automate your development workflow
275+
276+
277+
<!-- LINKS - external -->
278+
[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms/
279+
280+
<!-- LINKS - internal -->
281+
282+
[azure-cli-install]: /cli/azure/install-azure-cli
283+
[az-group-show]: /cli/azure/group#az-group-show
284+
[az-group-delete]: /cli/azure/group#az-group-delete
285+
[az-ad-sp-create-for-rbac]: /cli/azure/ad/sp#az-ad-sp-create-for-rbac
286+
[az-role-assignment-create]: /cli/azure/role/assignment#az-role-assignment-create
287+
[az-container-logs]: /cli/azure/container#az-container-logs
288+
[az-acr-show]: /cli/azure/acr#az-acr-show
289+
[az-container-show]: /cli/azure/container#az-container-show
290+
[az-container-delete]: /cli/azure/container#az-container-delete
291+
[az-extension-add]: /cli/azure/extension#az-extension-add
292+
[az-container-app-up]: /cliazure/container/app#az-container-app-up

‎articles/container-instances/media/container-instances-github-action/github-action-container.png

29.7 KB
Loading

‎articles/container-instances/media/container-instances-github-action/github-action-progress.png

25.5 KB
Loading

0 commit comments

Comments
 (0)