Skip to content

Commit d73a5a9

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #251188 from schaffererin/kubernetes-action-freshness-pass
kubernetes-action.md freshness pass
2 parents ef430c0 + 645376c commit d73a5a9

File tree

1 file changed

+147
-155
lines changed

1 file changed

+147
-155
lines changed

‎articles/aks/kubernetes-action.md

Lines changed: 147 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -1,199 +1,188 @@
11
---
2-
title: Build, test, and deploy containers to Azure Kubernetes Service using GitHub Actions
3-
description: Learn how to use GitHub Actions to deploy your container to Kubernetes
2+
title: Build, test, and deploy containers to Azure Kubernetes Service (AKS) using GitHub Actions
3+
description: Learn how to use GitHub Actions to build, test, and deploy containers to Azure Kubernetes Service (AKS).
44
ms.topic: article
5-
ms.date: 08/02/2022
5+
ms.date: 09/12/2023
66
ms.custom: github-actions-azure
77
---
88

9-
# GitHub Actions for deploying to Kubernetes service
9+
# Build, test, and deploy containers to Azure Kubernetes Service (AKS) using GitHub Actions
1010

11-
[GitHub Actions](https://docs.github.com/en/actions) gives you the flexibility to build an automated software development lifecycle workflow. You can use multiple Kubernetes actions to deploy to containers from Azure Container Registry to Azure Kubernetes Service with GitHub Actions.
11+
[GitHub Actions](https://docs.github.com/en/actions) gives you the flexibility to build an automated software development lifecycle workflow. You can use multiple Kubernetes actions to deploy to containers from Azure Container Registry (ACR) to Azure Kubernetes Service (AKS) with GitHub Actions.
1212

1313
## Prerequisites
1414

15-
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
16-
- A GitHub account. If you don't have one, sign up for [free](https://github.com/join).
17-
- An existing AKS cluster with an attached Azure Container Registry (ACR).
15+
- An Azure account with an active subscription. If you don't have one, [create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
16+
- A GitHub account. If you don't have one, [sign up for free](https://github.com/join).
17+
- When using GitHub Actions, you need to configure the integration between Azure and your GitHub repository. To configure the integration, see [Use GitHub Actions to connect to Azure][connect-gh-azure].
18+
- An existing AKS cluster with an attached ACR. If you don't have one, see [Authenticate with ACR from AKS](./cluster-container-registry-integration.md).
1819

19-
## Configure integration between Azure and your GitHub repository
20+
## GitHub Actions for AKS
2021

21-
When using GitHub Actions, you need to configure the integration between Azure and your GitHub repository. For more details on connecting your GitHub repository to Azure, see [Use GitHub Actions to connect to Azure][connect-gh-azure].
22+
With GiHub Actions, you can automate your software development workflows from within GitHub. For more information, see [GitHub Actions for Azure][github-actions].
2223

23-
## Available actions
24-
25-
GitHub Actions helps you automate your software development workflows from within GitHub. For more details on using GitHub Actions with Azure, see [What is GitHub Actions for Azures][github-actions].
26-
27-
The below table shows the available GitHub Actions that integrate specifically with AKS.
24+
The following table lists the available actions for AKS:
2825

2926
| Name | Description | More details |
3027
|---|---|---|
31-
|`azure/aks-set-context`|Set the target AKS cluster context which will be used by other actions or run any kubectl commands.|[azure/aks-set-context][azure/aks-set-context]|
32-
|`azure/k8s-set-context`|Set the target Kubernetes cluster context which will be used by other actions or run any kubectl commands.|[azure/k8s-set-context][azure/k8s-set-context]|
33-
|`azure/k8s-bake`|Bake manifest file to be used for deployments using Helm, kustomize or kompose.|[azure/k8s-bake][azure/k8s-bake]|
28+
|`azure/aks-set-context`|Set the target AKS cluster context for other actions to use or run any kubectl commands.|[azure/aks-set-context][azure/aks-set-context]|
29+
|`azure/k8s-set-context`|Set the target Kubernetes cluster context for other actions to use or run any kubectl commands.|[azure/k8s-set-context][azure/k8s-set-context]|
30+
|`azure/k8s-bake`|Bake manifest file to use for deployments using Helm, kustomize, or kompose.|[azure/k8s-bake][azure/k8s-bake]|
3431
|`azure/k8s-create-secret`|Create a generic secret or docker-registry secret in the Kubernetes cluster.|[azure/k8s-create-secret][azure/k8s-create-secret]|
3532
|`azure/k8s-deploy`|Deploy manifests to Kubernetes clusters.|[azure/k8s-deploy][azure/k8s-deploy]|
3633
|`azure/k8s-lint`|Validate/lint your manifest files.|[azure/k8s-lint][azure/k8s-lint]|
3734
|`azure/setup-helm`|Install a specific version of Helm binary on the runner.|[azure/setup-helm][azure/setup-helm]|
38-
|`azure/setup-kubectl`|Installs a specific version of kubectl on the runner.|[azure/setup-kubectl][azure/setup-kubectl]|
35+
|`azure/setup-kubectl`|Install a specific version of kubectl on the runner.|[azure/setup-kubectl][azure/setup-kubectl]|
3936
|`azure/k8s-artifact-substitute`|Update the tag or digest for container images.|[azure/k8s-artifact-substitute][azure/k8s-artifact-substitute]|
4037
|`azure/aks-create-action`|Create an AKS cluster using Terraform.|[azure/aks-create-action][azure/aks-create-action]|
4138
|`azure/aks-github-runner`|Set up self-hosted agents for GitHub Actions.|[azure/aks-github-runner][azure/aks-github-runner]|
39+
|`azure/acr-build`|Build containers using ACR.|[azure/acr-build][azure/acr-build]|
4240

43-
In addition, the example in the next section uses the [azure/acr-build][azure/acr-build] action.
44-
45-
## Example of using GitHub Actions with AKS
41+
## Use GitHub Actions with AKS
4642

4743
As an example, you can use GitHub Actions to deploy an application to your AKS cluster every time a change is pushed to your GitHub repository. This example uses the [Azure Vote][gh-azure-vote] application.
4844

4945
> [!NOTE]
50-
> This example uses a service principal for authentication with your ACR and AKS cluster. Alternatively, you can configure Open ID Connect (OIDC) and update the `azure/login` action to use OIDC. For more details, see [Set up Azure Login with OpenID Connect authentication][oidc-auth].
46+
> This example uses a service principal for authentication with your ACR and AKS cluster. Alternatively, you can configure Open ID Connect (OIDC) and update the `azure/login` action to use OIDC. For more information, see [Set up Azure Login with OpenID Connect authentication][oidc-auth].
5147
5248
### Fork and update the repository
5349

54-
Navigate to the [Azure Vote][gh-azure-vote] repository and click the **Fork** button.
50+
1. Navigate to the [Azure Vote][gh-azure-vote] repository and select **Fork**.
51+
2. Update the `azure-vote-all-in-one-redis.yaml` to use your ACR for the `azure-vote-front` image. Replace `<registryName>` with the name of your registry.
5552

56-
Once the repository is forked, update `azure-vote-all-in-one-redis.yaml` to use your ACR for the `azure-vote-front` image
53+
```yaml
54+
...
55+
containers:
56+
- name: azure-vote-front
57+
image: <registryName>.azurecr.io/azuredocs/azure-vote-front:v1
58+
...
59+
```
5760

58-
```yaml
59-
...
60-
containers:
61-
- name: azure-vote-front
62-
image: <registryName>.azurecr.io/azuredocs/azure-vote-front:v1
63-
...
64-
```
65-
66-
> [!IMPORTANT]
67-
> The update to `azure-vote-all-in-one-redis.yaml` must be committed to your repository before you can complete the later steps.
61+
3. Commit the updated `azure-vote-all-in-one-redis.yaml` to your repository.
6862

6963
### Create secrets
7064

71-
Create a service principal to access your resource group with the `Contributor` role using the following command, replacing:
72-
73-
- `<SUBSCRIPTION_ID>` with the subscription ID of your Azure account
74-
- `<RESOURCE_GROUP>` with the name of the resource group where your ACR is located
75-
76-
```azurecli-interactive
77-
az ad sp create-for-rbac \
78-
--name "ghActionAzureVote" \
79-
--scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP> \
80-
--role Contributor \
81-
--sdk-auth
82-
```
83-
84-
The following shows an example output from the above command.
85-
86-
```output
87-
{
88-
"clientId": <clientId>,
89-
"clientSecret": <clientSecret>,
90-
"subscriptionId": <subscriptionId>,
91-
"tenantId": <tenantId>,
92-
...
93-
}
94-
```
95-
96-
In your GitHub repository, create the below secrets for your action to use. To create a secret:
97-
1. Navigate to the repository's settings, and select **Security > Secrets and variables > Actions**.
98-
1. For each secret, click **New Repository Secret** and enter the name and value of the secret.
99-
100-
For more details on creating secrets, see [Encrypted Secrets][github-actions-secrets].
101-
102-
|Secret name |Secret value |
103-
|---------|---------|
104-
|AZURE_CREDENTIALS|The entire JSON output from the `az ad sp create-for-rbac` command|
105-
|service_principal | The value of `<clientId>`|
106-
|service_principal_password| The value of `<clientSecret>`|
107-
|subscription| The value of `<subscriptionId>`|
108-
|tenant|The value of `<tenantId>`|
109-
|registry|The name of your registry|
110-
|repository|azuredocs|
111-
|resource_group|The name of your resource group|
112-
|cluster_name|The name of your cluster|
113-
65+
1. Create a service principal to access your resource group with the `Contributor` role using the [`az ad sp create-for-rbac`][az-ad-sp-create-for-rbac] command. Replace `<SUBSCRIPTION_ID>` with the subscription ID of your Azure account and `<RESOURCE_GROUP>` with the name of the resource group containing your ACR.
66+
67+
```azurecli-interactive
68+
az ad sp create-for-rbac \
69+
--name "ghActionAzureVote" \
70+
--scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP> \
71+
--role Contributor \
72+
--sdk-auth
73+
```
74+
75+
Your output should look similar to the following example output:
76+
77+
```output
78+
{
79+
"clientId": <clientId>,
80+
"clientSecret": <clientSecret>,
81+
"subscriptionId": <subscriptionId>,
82+
"tenantId": <tenantId>,
83+
...
84+
}
85+
```
86+
87+
2. Navigate to your GitHub repository settings and select **Security** > **Secrets and variables** > **Actions**.
88+
3. For each secret, select **New Repository Secret** and enter the name and value of the secret.
89+
90+
|Secret name |Secret value |
91+
|---------|---------|
92+
|AZURE_CREDENTIALS|The entire JSON output from the `az ad sp create-for-rbac` command.|
93+
|service_principal | The value of `<clientId>`.|
94+
|service_principal_password| The value of `<clientSecret>`.|
95+
|subscription| The value of `<subscriptionId>`.|
96+
|tenant|The value of `<tenantId>`.|
97+
|registry|The name of your registry.|
98+
|repository|azuredocs|
99+
|resource_group|The name of your resource group.|
100+
|cluster_name|The name of your cluster.|
101+
102+
For more information about creating secrets, see [Encrypted Secrets][github-actions-secrets].
114103

115104
### Create actions file
116105

117-
Create a `.github/workflows/main.yml` in your repository with the following contents:
118-
119-
```yaml
120-
name: build_deploy_aks
121-
on:
122-
push:
123-
paths:
124-
- "azure-vote/**"
125-
jobs:
126-
build:
127-
runs-on: ubuntu-latest
128-
steps:
129-
- name: Checkout source code
130-
uses: actions/checkout@v3
131-
- name: ACR build
132-
id: build-push-acr
133-
uses: azure/acr-build@v1
134-
with:
135-
service_principal: ${{ secrets.service_principal }}
136-
service_principal_password: ${{ secrets.service_principal_password }}
137-
tenant: ${{ secrets.tenant }}
138-
registry: ${{ secrets.registry }}
139-
repository: ${{ secrets.repository }}
140-
image: azure-vote-front
141-
folder: azure-vote
142-
branch: master
143-
tag: ${{ github.sha }}
144-
- name: Azure login
145-
id: login
146-
uses: azure/[email protected]
147-
with:
148-
creds: ${{ secrets.AZURE_CREDENTIALS }}
149-
- name: Set AKS context
150-
id: set-context
151-
uses: azure/aks-set-context@v3
152-
with:
153-
resource-group: '${{ secrets.resource_group }}'
154-
cluster-name: '${{ secrets.cluster_name }}'
155-
- name: Setup kubectl
156-
id: install-kubectl
157-
uses: azure/setup-kubectl@v3
158-
- name: Deploy to AKS
159-
id: deploy-aks
160-
uses: Azure/k8s-deploy@v4
161-
with:
162-
namespace: 'default'
163-
manifests: |
164-
azure-vote-all-in-one-redis.yaml
165-
images: '${{ secrets.registry }}.azurecr.io/${{ secrets.repository }}/azure-vote-front:${{ github.sha }}'
166-
pull-images: false
167-
```
168-
169-
> [!IMPORTANT]
170-
> The `.github/workflows/main.yml` file must be committed to your repository before you can run the action.
171-
172-
The `on` section contains the event that triggers the action. In the above file, the action is triggered when a change is pushed to the `azure-vote` directory.
173-
174-
In the above file, the `steps` section contains each distinct action, which is executed in order:
175-
1. *Checkout source code* uses the [GitHub Actions Checkout Action][actions/checkout] to clone the repository.
176-
1. *ACR build* uses the [Azure Container Registry Build Action][azure/acr-build] to build the image and upload it to your registry.
177-
1. *Azure login* uses the [Azure Login Action][azure/login] to sign in to your Azure account.
178-
1. *Set AKS context* uses the [Azure AKS Set Context Action][azure/aks-set-context] to set the context for your AKS cluster.
179-
1. *Setup kubectl* uses the [Azure AKS Setup Kubectl Action][azure/setup-kubectl] to install kubectl on your runner.
180-
1. *Deploy to AKS* uses the [Azure Kubernetes Deploy Action][azure/k8s-deploy] to deploy the application to your Kuberentes cluster.
181-
182-
Confirm that the action is working by updating `azure-vote/azure-vote/config_file.cfg` to the following and pushing the changes to your repository:
183-
184-
```output
185-
# UI Configurations
186-
TITLE = 'Azure Voting App'
187-
VOTE1VALUE = 'Fish'
188-
VOTE2VALUE = 'Dogs'
189-
SHOWHOST = 'false'
190-
```
191-
192-
In your repository, click on *Actions* and confirm a workflow is running. Once complete, confirm the workflow has a green checkmark and the updated application is deployed to your cluster.
106+
1. In your repository, create a `.github/workflows/main.yml` and paste in the following contents:
107+
108+
```yaml
109+
name: build_deploy_aks
110+
on:
111+
push:
112+
paths:
113+
- "azure-vote/**"
114+
jobs:
115+
build:
116+
runs-on: ubuntu-latest
117+
steps:
118+
- name: Checkout source code
119+
uses: actions/checkout@v3
120+
- name: ACR build
121+
id: build-push-acr
122+
uses: azure/acr-build@v1
123+
with:
124+
service_principal: ${{ secrets.service_principal }}
125+
service_principal_password: ${{ secrets.service_principal_password }}
126+
tenant: ${{ secrets.tenant }}
127+
registry: ${{ secrets.registry }}
128+
repository: ${{ secrets.repository }}
129+
image: azure-vote-front
130+
folder: azure-vote
131+
branch: master
132+
tag: ${{ github.sha }}
133+
- name: Azure login
134+
id: login
135+
uses: azure/[email protected]
136+
with:
137+
creds: ${{ secrets.AZURE_CREDENTIALS }}
138+
- name: Set AKS context
139+
id: set-context
140+
uses: azure/aks-set-context@v3
141+
with:
142+
resource-group: '${{ secrets.resource_group }}'
143+
cluster-name: '${{ secrets.cluster_name }}'
144+
- name: Setup kubectl
145+
id: install-kubectl
146+
uses: azure/setup-kubectl@v3
147+
- name: Deploy to AKS
148+
id: deploy-aks
149+
uses: Azure/k8s-deploy@v4
150+
with:
151+
namespace: 'default'
152+
manifests: |
153+
azure-vote-all-in-one-redis.yaml
154+
images: '${{ secrets.registry }}.azurecr.io/${{ secrets.repository }}/azure-vote-front:${{ github.sha }}'
155+
pull-images: false
156+
```
157+
158+
The `on` section contains the event that triggers the action. In the example file, the action triggers when a change is pushed to the `azure-vote` directory.
159+
160+
The `steps` section contains each distinct action:
161+
162+
1. *Checkout source code* uses the [GitHub Actions Checkout Action][actions/checkout] to clone the repository.
163+
2. *ACR build* uses the [Azure Container Registry Build Action][azure/acr-build] to build the image and upload it to your registry.
164+
3. *Azure login* uses the [Azure Login Action][azure/login] to sign in to your Azure account.
165+
4. *Set AKS context* uses the [Azure AKS Set Context Action][azure/aks-set-context] to set the context for your AKS cluster.
166+
5. *Setup kubectl* uses the [Azure AKS Setup Kubectl Action][azure/setup-kubectl] to install kubectl on your runner.
167+
6. *Deploy to AKS* uses the [Azure Kubernetes Deploy Action][azure/k8s-deploy] to deploy the application to your Kubernetes cluster.
168+
169+
2. Commit the `.github/workflows/main.yml` file to your repository.
170+
3. To confirm the action is working, update the `azure-vote/azure-vote/config_file.cfg` with the following contents:
171+
172+
```cfg
173+
# UI Configurations
174+
TITLE = 'Azure Voting App'
175+
VOTE1VALUE = 'Fish'
176+
VOTE2VALUE = 'Dogs'
177+
SHOWHOST = 'false'
178+
```
179+
180+
4. Commit the updated `azure-vote/azure-vote/config_file.cfg` to your repository.
181+
5. In your repository, select **Actions** and confirm a workflow is running. Then, confirm the workflow has a green checkmark and the updated application is deployed to your cluster.
193182

194183
## Next steps
195184

196-
Review the following starter workflows for AKS. For more details on using starter workflows, see [Using starter workflows][use-starter-workflows].
185+
Review the following starter workflows for AKS. For more information, see [Using starter workflows][use-starter-workflows].
197186

198187
- [Azure Kubernetes Service (Basic)][aks-swf-basic]
199188
- [Azure Kubernetes Service Helm][aks-swf-helm]
@@ -206,6 +195,8 @@ Review the following starter workflows for AKS. For more details on using starte
206195
> [!div class="nextstepaction"]
207196
> [Learn about Azure Kubernetes Service](/azure/architecture/reference-architectures/containers/aks-start-here)
208197

198+
<!-- LINKS --->
199+
209200
[oidc-auth]: /azure/developer/github/connect-from-azure?tabs=azure-cli%2Clinux#use-the-azure-login-action-with-openid-connect
210201
[aks-swf-basic]: https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service.yml
211202
[aks-swf-helm]: https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service-helm.yml
@@ -230,3 +221,4 @@ Review the following starter workflows for AKS. For more details on using starte
230221
[connect-gh-azure]: /azure/developer/github/connect-from-azure?tabs=azure-cli%2Clinux
231222
[gh-azure-vote]: https://github.com/Azure-Samples/azure-voting-app-redis
232223
[actions/checkout]: https://github.com/actions/checkout
224+
[az-ad-sp-create-for-rbac]: /cli/azure/ad/sp#az-ad-sp-create-for-rbac

0 commit comments

Comments
 (0)