GitHub Actions for deploying to Kubernetes service

Article
02/27/2023
5 minutes to read

GitHub 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.

Prerequisites

An Azure account with an active subscription. Create an account for free.
A GitHub account. If you don't have one, sign up for free.
An existing AKS cluster with an attached Azure Container Registry (ACR).

Configure integration between Azure and your GitHub repository

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.

Available actions

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.

The below table shows the available GitHub Actions that integrate specifically with AKS.

Name	Description	More details
`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/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-bake`	Bake manifest file to be used for deployments using Helm, kustomize or kompose.	azure/k8s-bake
`azure/k8s-create-secret`	Create a generic secret or docker-registry secret in the Kubernetes cluster.	azure/k8s-create-secret
`azure/k8s-deploy`	Deploy manifests to Kubernetes clusters.	azure/k8s-deploy
`azure/k8s-lint`	Validate/lint your manifest files.	azure/k8s-lint
`azure/setup-helm`	Install a specific version of Helm binary on the runner.	azure/setup-helm
`azure/setup-kubectl`	Installs a specific version of kubectl on the runner.	azure/setup-kubectl
`azure/k8s-artifact-substitute`	Update the tag or digest for container images.	azure/k8s-artifact-substitute
`azure/aks-create-action`	Create an AKS cluster using Terraform.	azure/aks-create-action
`azure/aks-github-runner`	Set up self-hosted agents for GitHub Actions.	azure/aks-github-runner

In addition, the example in the next section uses the azure/acr-build action.

Example of using GitHub Actions with AKS

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 application.

Note

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.

Fork and update the repository

Navigate to the Azure Vote repository and click the Fork button.

Once the repository is forked, update azure-vote-all-in-one-redis.yaml to use your ACR for the azure-vote-front image

...
      containers:
      - name: azure-vote-front
        image: <registryName>.azurecr.io/azuredocs/azure-vote-front:v1
...

Important

The update to azure-vote-all-in-one-redis.yaml must be committed to your repository before you can complete the later steps.

Create secrets

Create a service principal to access your resource group with the Contributor role using the following command, replacing:

<SUBSCRIPTION_ID> with the subscription ID of your Azure account
<RESOURCE_GROUP> with the name of the resource group where your ACR is located

az ad sp create-for-rbac \
    --name "ghActionAzureVote" \
    --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP> \
    --role Contributor \
    --sdk-auth

The following shows an example output from the above command.

{
  "clientId": <clientId>,
  "clientSecret": <clientSecret>,
  "subscriptionId": <subscriptionId>,
  "tenantId": <tenantId>,
  ...
}

In your GitHub repository, create the below secrets for your action to use. To create a secret:

Navigate to the repository's settings, and select Security > Secrets and variables > Actions.
For each secret, click New Repository Secret and enter the name and value of the secret.

For more details on creating secrets, see Encrypted Secrets.

Secret name	Secret value
AZURE_CREDENTIALS	The entire JSON output from the `az ad sp create-for-rbac` command
service_principal	The value of `<clientId>`
service_principal_password	The value of `<clientSecret>`
subscription	The value of `<subscriptionId>`
tenant	The value of `<tenantId>`
registry	The name of your registry
repository	azuredocs
resource_group	The name of your resource group
cluster_name	The name of your cluster

Create actions file

Create a .github/workflows/main.yml in your repository with the following contents:

name: build_deploy_aks
on:
  push:
    paths:
      - "azure-vote/**"
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source code 
        uses: actions/checkout@v3
      - name: ACR build
        id: build-push-acr
        uses: azure/acr-build@v1
        with:
          service_principal: ${{ secrets.service_principal }}
          service_principal_password: ${{ secrets.service_principal_password }}
          tenant: ${{ secrets.tenant }}
          registry: ${{ secrets.registry }}
          repository: ${{ secrets.repository }}
          image:  azure-vote-front
          folder: azure-vote
          branch: master
          tag: ${{ github.sha }}
      - name: Azure login
        id: login
        uses: azure/login@v1.4.3
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
      - name: Set AKS context
        id: set-context
        uses: azure/aks-set-context@v3
        with:
          resource-group: '${{ secrets.resource_group }}' 
          cluster-name: '${{ secrets.cluster_name }}'
      - name: Setup kubectl
        id: install-kubectl
        uses: azure/setup-kubectl@v3
      - name: Deploy to AKS
        id: deploy-aks
        uses: Azure/k8s-deploy@v4
        with:
          namespace: 'default'
          manifests: |
             azure-vote-all-in-one-redis.yaml
          images: '${{ secrets.registry }}.azurecr.io/${{ secrets.repository }}/azure-vote-front:${{ github.sha }}'
          pull-images: false

Important

The .github/workflows/main.yml file must be committed to your repository before you can run the action.

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.

In the above file, the steps section contains each distinct action, which is executed in order:

Checkout source code uses the GitHub Actions Checkout Action to clone the repository.
ACR build uses the Azure Container Registry Build Action to build the image and upload it to your registry.
Azure login uses the Azure Login Action to sign in to your Azure account.
Set AKS context uses the Azure AKS Set Context Action to set the context for your AKS cluster.
Setup kubectl uses the Azure AKS Setup Kubectl Action to install kubectl on your runner.
Deploy to AKS uses the Azure Kubernetes Deploy Action to deploy the application to your Kuberentes cluster.

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:

# UI Configurations
TITLE = 'Azure Voting App'
VOTE1VALUE = 'Fish'
VOTE2VALUE = 'Dogs'
SHOWHOST = 'false'

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.

Next steps

Review the following starter workflows for AKS. For more details on using starter workflows, see Using starter workflows.

Learn how to create multiple pipelines on GitHub Actions with AKS

Learn about Azure Kubernetes Service