はじめに

本記事は Qiita エンジニアフェスタ 2022 GitHub Actions の自分流の使い方をシェアしようの参加記事です。

学習用に自宅でKubernetesクラスターを動かしているので、これをGitHub Actionsと組み合わせようと思い立ちました。
どうやってGitHub Actionsから自宅クラスターにアクセスさせようか悩んでいたところ、Azure Arc 対応 Kubernetes の任意の場所からクラスターにアクセスする機能が使えそうだとわかりました。
本記事ではKubernetesクラスターをAzure Arcに接続し、GitHub Actionsで操作するところまでの手順を解説します。

環境

以下の図の構成を作ります。

Kubernetesクラスターの環境は以下のとおりです。

ノードOS: Ubuntu Server 22.04
Kubernetesバージョン: 1.24.2

Azure Arc 対応 Kubernetes を使うには、クラスターに1台以上amd64のノードが必要となります。
おうちKubernetesでよくあるRaspberry Piだけで構築したクラスターには残念ながら導入できません。amd64のノードを追加しましょう。

Azure Arc 対応 Kubernetesの設定

公式ドキュメントに記載の手順に従い作業を実施します。

準備作業

Azure CLIに connectedk8s 拡張機能を導入します。

az extension add --name connectedk8s

インストール済みの拡張機能を最新化するときは以下コマンドを実行します。

az extension update --name connectedk8s

Azure Arc 対応 Kubernetes用のプロバイダーをインストールします。

az provider register --namespace Microsoft.Kubernetes

az provider register --namespace Microsoft.KubernetesConfiguration

az provider register --namespace Microsoft.ExtendedLocation

3つとも Registered になればOKです。

$ az provider show -n Microsoft.Kubernetes -o table
Namespace             RegistrationPolicy    RegistrationState
--------------------  --------------------  -------------------
Microsoft.Kubernetes  RegistrationRequired  Registered

$ az provider show -n Microsoft.KubernetesConfiguration -o table
Namespace                          RegistrationPolicy    RegistrationState
---------------------------------  --------------------  -------------------
Microsoft.KubernetesConfiguration  RegistrationRequired  Registered

$ az provider show -n Microsoft.ExtendedLocation -o table
Namespace                   RegistrationPolicy    RegistrationState
--------------------------  --------------------  -------------------
Microsoft.ExtendedLocation  RegistrationRequired  Registered

リソースグループを作成します。ここでは AzureArc という名前で、東日本リージョンに作成しています。

az group create --name AzureArc --location japaneast

以上で事前の準備作業は完了です。

KubernetesクラスターをAzure Arcへ接続する

以下のコマンドでKubernetesクラスターをAzure Arcへ接続します。
--name でAzure上での名前を設定します。ここでは HomeCluster としました。

az connectedk8s connect --name HomeCluster --resource-group AzureArc

コマンドの実行が終わると、Azure上にAzure Arc 対応 Kubernetesのリソースが作成されていることが確認できます。

また、Kubernetes上では azure-arc Namespace配下でPodが起動していることが確認できます。

$ kubectl get pod -n azure-arc
NAME                                         READY   STATUS    RESTARTS   AGE
cluster-metadata-operator-855c68dcf8-l62w2   2/2     Running   0          6m55s
clusterconnect-agent-77496f7c5c-txjnx        3/3     Running   0          6m55s
clusteridentityoperator-6d74bff55b-89lf8     2/2     Running   0          6m55s
config-agent-65b55bccd9-ph4vr                2/2     Running   0          6m55s
controller-manager-7fcbd6585d-ss5hx          2/2     Running   0          6m55s
extension-manager-767db884cd-bs54v           2/2     Running   0          6m55s
flux-logs-agent-68bc745586-qjd8q             1/1     Running   0          6m55s
kube-aad-proxy-fdf494d66-htn9v               2/2     Running   0          6m55s
metrics-agent-7d6844cd4c-qblcj               2/2     Running   0          6m55s
resource-sync-agent-5d755f9d6f-vgml7         2/2     Running   0          6m55s

クラスター接続の設定

Azure Arc 対応 Kubernetesの クラスター接続 機能を使うことで、ネットワーク的にKubernetesクラスターと疎通性がない場所からAzureを介して操作をすることができます。
公式ドキュメントで手順が案内されているので、順に作業を行います。
（2022/07/02時点では日本語版ドキュメントの手順では一部うまく動かないため、英語版ドキュメントを参照しています）

以下のコマンドでクラスター接続機能を有効にします。

az connectedk8s enable-features --features cluster-connect -n HomeCluster -g AzureArc

次に接続に使うサービスアカウントを作成します。
ここでは arc-admin という名前のサービスアカウントを azure-arc Namespaceに作成します。

kubectl create serviceaccount arc-admin -n azure-arc

続いて、ClusterRoleBindingを作成し、サービスアカウントに対しアクセス許可を割り当てます。

kubectl create clusterrolebinding arc-admin-binding --clusterrole cluster-admin --serviceaccount azure-arc:arc-admin

最後にサービスアカウントのトークンを取得します。
以下のコマンドでSecretを生成し、

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: arc-admin-secret
  namespace: azure-arc
  annotations:
    kubernetes.io/service-account.name: arc-admin
type: kubernetes.io/service-account-token
EOF

トークンを取得します。

TOKEN=$(kubectl get secret arc-admin-secret -n azure-arc -o jsonpath='{$.data.token}' | base64 -d | sed $'s/$/\\\n/g')

取得したトークンは後ほど使用します。

ここまででAzure Arc 対応 Kubernetesの準備は完了です。

GitHub Actionsの準備

ここからはAzure Arc 対応 Kubernetesに対するデプロイを行うGitHub Actionsの準備を行います。

GitHubリポジトリの作成

まずはGitHubのリポジトリを作成しましょう。GitHub CLIを利用します。

gh repo create homecluster-manage --private

OpenID Connect

GitHub ActionsからAzureリソースを操作するために OpenID Connect を利用します。
手で設定してもいいのですが、Microsoftが公開している Draft というツールを使うと楽に設定できるので今回はこちらを使用します。

Azure CLIに aks-preview 拡張機能を導入します。

az extension add --name aks-preview

過去にインストール済みの場合は以下コマンドで最新化します。

az extension update --name aks-preview

拡張機能を導入したら、以下コマンドで Draft を起動します。

az aks draft setup-gh

起動後は対話形式のプロンプトが表示されるので、順に入力していきます。

# Azure AD に登録するアプリの名前を入力
✔ Enter app registration name: homecluster-gitops
# Azure サブスクリプションを選択する
Use the arrow keys to navigate: ↓ ↑ → ←
✔ ########-####-####-####-############
? Please choose the subscription ID you would like to use.:
# Azure リソースグループの名前を入力
✔ Enter resource group name: AzureArc
# GitHub リポジトリの名前を入力
✔ Enter github organization and repo (organization/repoName): ussvgr/homecluster-manage

[Draft] Draft has successfully set up Github OIDC for your project 😃
[Draft] Use 'draft generate-workflow' to generate a Github workflow to build and deploy an application on AKS.

完了すると、Azure ADにアプリが追加され、フェデレーション資格情報の設定も完了しています。

GitHubリポジトリ側も、認証に必要なSecretsが入力された状態になっています。

トークンの追加

GitHub ActionsからAzure Arc 対応 Kubernetesを操作するために、前の項で作成したトークンをGitHub ActionsのSecretsに追加します。

ここでもGitHub CLIを利用します。SA_TOKEN という名前でSecretを作成します。

gh secret set SA_TOKEN --app actions --body $TOKEN --repo ussvgr/homecluster-manage

マニフェストとワークフローの準備

Kubernetesクラスターにデプロイするマニフェストと、GitHub Actionsのワークフローを準備します。
以下のような構成でローカルのディレクトリ内にファイルを配置します。

.
├── .github
│   └── workflows
│       └── deploy-to-arc.yaml
└── manifests
    └── sampleapp.yaml

各ファイルの中身は以下のとおりです。
GitHub Actionsのワークフローがこちら。

deploy-to-arc.yaml

name: deploy to Azure Arc Enabled Kubernetes
"on":
    push:
        branches:
            - main
    workflow_dispatch: null
env:
    DEPLOYMENT_MANIFEST_PATH: ./manifests
jobs:
    deploy:
        permissions:
            actions: read
            contents: read
            id-token: write
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3
            - name: Azure login
              uses: azure/login@v1
              with:
                client-id: ${{ secrets.AZURE_CLIENT_ID }}
                subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
                tenant-id: ${{ secrets.AZURE_TENANT_ID }}
            - name: Get K8s context
              uses: azure/k8s-set-context@v3
              with:
                method: service-account
                cluster-type: arc
                cluster-name: HomeCluster
                resource-group: AzureArc
                token: ${{ secrets.SA_TOKEN }}
            - name: Deploys application
              uses: Azure/k8s-deploy@v4
              with:
                action: deploy
                manifests: ${{ env.DEPLOYMENT_MANIFEST_PATH }}

Kubernetesにデプロイするマニフェストがこちらです。
sampleapp という名前でnginxを起動するのみの簡易なものです。

sampleapp.yaml

---
apiVersion: v1
kind: Service
metadata:
  name: sampleapp
spec:
  type: LoadBalancer
  selector:
    app: sampleapp
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sampleapp
  labels:
    app: sampleapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sampleapp
  template:
    metadata:
      labels:
        app: sampleapp
    spec:
      containers:
        - name: sampleapp
          image: nginx:latest
          ports:
            - containerPort: 80

GitHub Actionsによるデプロイ

前節までの作業で準備が完了したので、GitHubにPushしてGitHub Actionsを起動してみましょう。

git init
git add -A
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:ussvgr/homecluster-manage
git push -u origin main

ジョブが正常に完了すると…

Kubernetesクラスターに sampleapp がデプロイされています！

$ kubectl get pod
NAME                         READY   STATUS    RESTARTS   AGE
sampleapp-596d47dffb-6szm7   1/1     Running   0          30s
$ kubectl get svc
NAME         TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)        AGE
kubernetes   ClusterIP      10.96.0.1      <none>         443/TCP        53d
sampleapp    LoadBalancer   10.100.6.247   192.168.11.0   80:32533/TCP   37s

おわりに

Azure Arc 対応 Kubernetesで本格的なGitOpsを行う場合、最近GAした Flux v2 を利用するのが一般的な手順になるでしょう。
とはいえ、Flux v2を利用するとKubernetesクラスターの規模によっては若干の費用が発生します。

なるべくお金を掛けたくない方向けに、簡易的なことであればGitHub Actionsでもできますよ、という紹介でした。
皆様のおうちKubernetes運用の一助になれば幸いです。