Skip to content

Commit ab0f7bc

Browse files
megvanhuygenmegvanhuygen
authored
Merge pull request #108101 from dlepow/acigh
[ACI] GitHub action
2 parents 6be3f1f + f6f7e0a commit ab0f7bc

File tree

4 files changed

+301
-0
lines changed

4 files changed

+301
-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: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
---
2+
title: Deploy container instance 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/18/2020
6+
ms.custom:
7+
---
8+
9+
# Configure a GitHub action to create a container instance
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 the [Deploy to Azure Container Instances](https://github.com/azure/aci-deploy) GitHub action to automate deployment of a container to Azure Container Instances. The action allows you to set properties for a container instance similar to those in the [az container create][az-container-create] command.
14+
15+
This article shows how to set up a workflow in a GitHub repo that performs the following actions:
16+
17+
* Build an image from a Dockerfile
18+
* Push the image to an Azure container registry
19+
* Deploy the container image to an Azure container instance
20+
21+
This article shows two ways to set up the workflow:
22+
23+
* Configure a workflow yourself in a GitHub repo using the Deploy to Azure Container Instances action and other actions.
24+
* 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.
25+
26+
> [!IMPORTANT]
27+
> 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).
28+
29+
## Prerequisites
30+
31+
* **GitHub account** - Create an account on https://github.com if you don't already have one.
32+
* **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].
33+
* **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.
34+
35+
## Set up 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 and source files 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 <resource-group-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 the GitHub workflow 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+
1. In the GitHub UI, navigate to your forked repository and select **Settings** > **Secrets**.
111+
112+
1. Select **Add a new secret** to add the following secrets:
113+
114+
|Secret |Value |
115+
|---------|---------|
116+
|`AZURE_CREDENTIALS` | The entire JSON output from the service principal creation |
117+
|`REGISTRY_LOGIN_SERVER` | The login server name of your registry (all lowercase). Example: *myregistry.azure.cr.io* |
118+
|`REGISTRY_USERNAME` | The `clientId` from the JSON output from the service principal creation |
119+
|`REGISTRY_PASSWORD` | The `clientSecret` from the JSON output from the service principal creation |
120+
| `RESOURCE_GROUP` | The name of the resource group you used to scope the service principal |
121+
122+
### Create workflow file
123+
124+
1. In the GitHub UI, select **Actions** > **New workflow**.
125+
1. Select **Set up a workflow yourself**.
126+
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.
127+
1. Select **Start commit**, optionally provide short and extended descriptions of your commit, and select **Commit new file**.
128+
129+
```yml
130+
on: [push]
131+
name: Linux_Container_Workflow
132+
133+
jobs:
134+
build-and-deploy:
135+
runs-on: ubuntu-latest
136+
steps:
137+
# checkout the repo
138+
- name: 'Checkout GitHub Action'
139+
uses: actions/checkout@master
140+
141+
- name: 'Login via Azure CLI'
142+
uses: azure/login@v1
143+
with:
144+
creds: ${{ secrets.AZURE_CREDENTIALS }}
145+
146+
- name: 'Build and push image'
147+
uses: azure/docker-login@v1
148+
with:
149+
login-server: ${{ secrets.REGISTRY_LOGIN_SERVER }}
150+
username: ${{ secrets.REGISTRY_USERNAME }}
151+
password: ${{ secrets.REGISTRY_PASSWORD }}
152+
- run: |
153+
docker build . -t ${{ secrets.REGISTRY_LOGIN_SERVER }}/sampleapp:${{ github.sha }}
154+
docker push ${{ secrets.REGISTRY_LOGIN_SERVER }}/sampleapp:${{ github.sha }}
155+
156+
- name: 'Deploy to Azure Container Instances'
157+
uses: 'azure/aci-deploy@v1'
158+
with:
159+
resource-group: ${{ secrets.RESOURCE_GROUP }}
160+
dns-name-label: ${{ secrets.RESOURCE_GROUP }}${{ github.run_number }}
161+
image: ${{ secrets.REGISTRY_LOGIN_SERVER }}/sampleapp:${{ github.sha }}
162+
registry-login-server: ${{ secrets.REGISTRY_LOGIN_SERVER }}
163+
registry-username: ${{ secrets.REGISTRY_USERNAME }}
164+
registry-password: ${{ secrets.REGISTRY_PASSWORD }}
165+
name: aci-sampleapp
166+
location: 'west us'
167+
```
168+
169+
### Validate workflow
170+
171+
After you commit the workflow file, the workflow is triggered. To review workflow progress, navigate to **Actions** > **Workflows**.
172+
173+
![View workflow progress](./media/container-instances-github-action/github-action-progress.png)
174+
175+
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.
176+
177+
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:
178+
179+
```azurecli
180+
az container show \
181+
--resource-group <resource-group-name> \
182+
--name aci-sampleapp \
183+
--query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \
184+
--output table
185+
```
186+
187+
Output is similar to:
188+
189+
```console
190+
FQDN ProvisioningState
191+
--------------------------------- -------------------
192+
aci-action01.westus.azurecontainer.io Succeeded
193+
```
194+
195+
After the instance is provisioned, navigate to the container's FQDN in your browser to view the running web app.
196+
197+
![Running web app in browser](./media/container-instances-github-action/github-action-container.png)
198+
199+
## Use Deploy to Azure extension
200+
201+
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 input parameters from you to set up a workflow to deploy to Azure Container Instances.
202+
203+
The workflow created by the Azure CLI is similar to the workflow you can [create manually using GitHub](#configure-github-workflow).
204+
205+
### Additional prerequisite
206+
207+
In addition to the [prerequisites](#prerequisites) and [repo setup](#set-up-repo) for this scenario, you need to install the **Deploy to Azure extension** for the Azure CLI.
208+
209+
Run the [az extension add][az-extension-add] command to install the extension:
210+
211+
```azurecli
212+
az extension add \
213+
--name deploy-to-azure
214+
```
215+
216+
For information about finding, installing, and managing extensions, see [Use extensions with Azure CLI](/cli/azure/azure-cli-extensions-overview).
217+
218+
### Run `az container app up`
219+
220+
To run the [az container app up][az-container-app-up] command, provide at minimum:
221+
222+
* The name of your Azure container registry, for example, *myregistry*
223+
* The URL to your GitHub repo, for example, `https://github.com/<your-GitHub-Id>/acr-build-helloworld-node`
224+
225+
Sample command:
226+
227+
```azurecli
228+
az container app up \
229+
--acr myregistry \
230+
--repository https://github.com/myID/acr-build-helloworld-node
231+
```
232+
233+
### Command progress
234+
235+
* When prompted, provide your GitHub credentials or provide a [GitHub personal access token](https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) (PAT) that has *repo* and *user* scopes to authenticate with your registry. If you provide GitHub credentials, the command creates a PAT for you.
236+
237+
* The command creates repo secrets for the workflow:
238+
239+
* Service principal credentials for the Azure CLI
240+
* Credentials to access the Azure container registry
241+
242+
* After the command commits the workflow file to your repo, the workflow is triggered.
243+
244+
Output is similar to:
245+
246+
```console
247+
[...]
248+
Checking in file github/workflows/main.yml in the Github repository myid/acr-build-helloworld-node
249+
Creating workflow...
250+
GitHub Action Workflow has been created - https://github.com/myid/acr-build-helloworld-node/runs/515192398
251+
GitHub workflow completed.
252+
Workflow succeeded
253+
Your app is deployed at: http://acr-build-helloworld-node.eastus.azurecontainer.io:8080/
254+
```
255+
256+
### Validate workflow
257+
258+
The workflow deploys an Azure container instance with the base name of your GitHub repo, in this case, *acr-build-helloworld-node*. In your browser, you can browse to the link provided to view the running web app. If your app listens on a port other than 8080, specify that in the URL instead.
259+
260+
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).
261+
262+
## Clean up resources
263+
264+
Stop the container instance with the [az container delete][az-container-delete] command:
265+
266+
```azurecli
267+
az container delete \
268+
--name <instance-name>
269+
--resource-group <resource-group-name>
270+
```
271+
272+
To delete the resource group and all the resources in it, run the [az group delete][az-group-delete] command:
273+
274+
```azurecli
275+
az group delete \
276+
--name <resource-group-name>
277+
```
278+
279+
## Next steps
280+
281+
Browse the [GitHub Marketplace](https://github.com/marketplace?type=actions) for more actions to automate your development workflow
282+
283+
284+
<!-- LINKS - external -->
285+
[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms/
286+
287+
<!-- LINKS - internal -->
288+
289+
[azure-cli-install]: /cli/azure/install-azure-cli
290+
[az-group-show]: /cli/azure/group#az-group-show
291+
[az-group-delete]: /cli/azure/group#az-group-delete
292+
[az-ad-sp-create-for-rbac]: /cli/azure/ad/sp#az-ad-sp-create-for-rbac
293+
[az-role-assignment-create]: /cli/azure/role/assignment#az-role-assignment-create
294+
[az-container-create]: /cli/azure/container#az-container-create
295+
[az-acr-show]: /cli/azure/acr#az-acr-show
296+
[az-container-show]: /cli/azure/container#az-container-show
297+
[az-container-delete]: /cli/azure/container#az-container-delete
298+
[az-extension-add]: /cli/azure/extension#az-extension-add
299+
[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)