kubectlプラグイン開発とKrewによる管理

Tech

本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。

kubectlプラグイン開発とKrewによる管理

Kubernetes環境の運用において、kubectlコマンドの機能拡張は、作業の効率化と自動化に不可欠です。本記事では、オリジナルのkubectlプラグインを開発し、その配布と管理にKrewを利用する方法、さらにsystemdを用いてプラグインを定期実行する手順について、DevOpsエンジニアの視点から解説します。特に、安全なシェルスクリプトの書き方、権限管理、およびトラブルシューティングに重点を置きます。

1. 要件と前提

本ガイドを進めるにあたり、以下のツールと環境がインストールされ、適切に設定されていることを前提とします。

  • Kubernetesクラスタとkubectl: kubectlコマンドが動作し、Kubernetesクラスタにアクセスできること。

  • Krew: kubectlプラグインマネージャーKrewがインストールされていること。Krewのインストール手順はKrew公式サイトを参照してください。最新安定版は2024年5月22日にリリースされたv0.4.4です。

  • jq: JSON処理ツール。

  • curl: HTTPリクエストツール。TLS検証やリトライ機能が重要です。

  • Bash: シェルスクリプト実行環境。

  • systemd: Linuxディストリビューションに付属するサービスマネージャー。

  • 実行パス (PATH): 作成するkubectlプラグインがシェルから実行可能であるために、適切なディレクトリがPATH環境変数に含まれている必要があります。Krewは自動的に~/.krew/binをPATHに追加するよう指示します。

2. 実装

2.1. kubectlプラグイン本体の作成

kubectlプラグインは、kubectl-で始まる実行可能ファイルであれば何でも構いません。ここでは、GitHubのパブリックAPIから特定の情報を取得し、JSONを整形して表示するシンプルなプラグインkubectl-repo-infoを作成します。

セキュリティに関する注意点: プラグインはユーザーの環境で実行されるため、安易にroot権限を必要とする操作を含めるべきではありません。必要であれば、特定のコマンドのみsudoを利用し、その権限範囲を最小限に抑えるべきです。今回の例ではroot権限は不要です。

#!/bin/bash


# ファイル名: kubectl-repo-info

# 堅牢なシェルスクリプトのベストプラクティス


# -e: コマンドが失敗した場合、即座に終了


# -u: 未定義の変数が使用された場合、エラーとして終了


# -o pipefail: パイプライン中のコマンドが失敗した場合、パイプライン全体が失敗する

set -euo pipefail

# 一時ディレクトリの作成と終了時のクリーンアップ


# mktemp -d: 一意の一時ディレクトリを作成

tmpdir=$(mktemp -d)

# trap: スクリプト終了時に一時ディレクトリを削除

trap 'rm -rf "$tmpdir"' EXIT

# --- 関数定義 ---

# ヘルプメッセージを表示する関数

show_help() {
    echo "Usage: kubectl repo-info <owner> <repo_name>"
    echo "       kubectl repo-info --help"
    echo ""
    echo "Fetch repository information from GitHub API."
    exit 0
}

# エラーメッセージを表示して終了する関数

error_exit() {
    echo "Error: $1" >&2
    exit 1
}

# --- メイン処理 ---

# 引数チェック

if [[ "$#" -ne 2 ]]; then
    if [[ "$#" -eq 1 && ("$1" == "--help" || "$1" == "-h") ]]; then
        show_help
    else
        error_exit "Incorrect number of arguments. Expected 2 (owner, repo_name)."
    fi
fi

OWNER="$1"
REPO_NAME="$2"
GITHUB_API_URL="https://api.github.com/repos/${OWNER}/${REPO_NAME}"

echo "Fetching repository info for ${OWNER}/${REPO_NAME}..."

# curlでGitHub APIからデータを取得


# --fail-with-body: HTTPエラーコードの場合でもボディを出力し、curlを失敗させる


# --silent --show-error: エラーメッセージを表示し、通常出力を抑制


# --retry 5 --retry-delay 5 --retry-max-time 60: 5秒間隔で最大5回リトライ、合計60秒まで


# --cacert: 証明書バンドルを指定 (多くのシステムでは不要だが、明示的なセキュリティ強化)


#           通常、システムのデフォルト証明書が使われるが、特定の環境では必要


#           例: `--cacert /etc/ssl/certs/ca-certificates.crt` または `--cacert /etc/pki/tls/certs/ca-bundle.crt`


#           今回はシステムデフォルトに任せるためコメントアウト

json_data=$(curl \
    --fail-with-body \
    --silent --show-error \
    --retry 5 --retry-delay 5 --retry-max-time 60 \
    "${GITHUB_API_URL}" || error_exit "Failed to fetch data from GitHub API.")

# jqでJSONデータを整形・抽出


# . as $repo: 全体を$repo変数に格納


# { name: $repo.name, description: $repo.description, stars: $repo.stargazers_count, url: $repo.html_url }: 特定のフィールドを抽出して新しいオブジェクトを作成


# -e: 出力がnullまたはfalseの場合、jqは終了コード1を返す


# --exit-status: 最終的なjqコマンドの終了ステータスをそのまま出力

if ! echo "${json_data}" | jq -e '. as $repo | { name: $repo.name, description: $repo.description, stars: $repo.stargazers_count, url: $repo.html_url }'; then
    error_exit "Failed to parse JSON data or repository not found."
fi

echo ""
echo "Plugin execution completed."

このスクリプトをkubectl-repo-infoという名前で保存し、実行権限を与えます。 chmod +x kubectl-repo-info

2.2. Krewプラグインマニフェストの作成

Krewでプラグインを管理するには、プラグインのメタデータと配布情報を含むYAMLファイル（プラグインマニフェスト）が必要です。

# ファイル名: repo-info.yaml

apiVersion: krew.googlecontainertools.github.com/v1alpha2
kind: Plugin
metadata:
  name: repo-info
spec:
  version: "v0.1.0" # プラグインのバージョン
  homepage: "https://github.com/your-org/your-kubectl-plugins" # プロジェクトのホームページ (任意)
  shortDescription: "Fetches GitHub repository information."
  description: |
    This plugin fetches the name, description, star count, and URL
    of a specified GitHub repository using the GitHub API.
  caveats: |
    This plugin requires 'curl' and 'jq' to be installed and available in PATH.
  platforms:

    - selector:

        # Linux x86_64

        matchLabels:
          os: linux
          arch: amd64
      uri: "https://github.com/your-org/your-kubectl-plugins/releases/download/v0.1.0/kubectl-repo-info-linux-amd64.tar.gz"
      sha256: "YOUR_LINUX_AMD64_SHA256_CHECKSUM" # ここに実際のSHA256ハッシュ値を記述
      bin: "kubectl-repo-info"

    - selector:

        # macOS x86_64

        matchLabels:
          os: darwin
          arch: amd64
      uri: "https://github.com/your-org/your-kubectl-plugins/releases/download/v0.1.0/kubectl-repo-info-darwin-amd64.tar.gz"
      sha256: "YOUR_DARWIN_AMD64_SHA256_CHECKSUM" # ここに実際のSHA256ハッシュ値を記述
      bin: "kubectl-repo-info"

    # その他のプラットフォームも追加可能 (windows, arm64など)

注意: uriとsha256は、実際にプラグインバイナリをGitHub Releasesなどにアップロードした後に正確な値を記述する必要があります。この例では、シェルスクリプトを直接配布する代わりに、バイナリとしてパッケージングして配布することを想定しています。

2.3. systemd Unit/Timerの作成

kubectlプラグインを定期的に実行したい場合、systemdのUnitとTimerを組み合わせるのが効果的です。ここでは、kubectl-repo-infoを毎日午前3時に実行し、ログに結果を記録する例を示します。

2.3.1. systemd Unitファイル (.service)

まず、プラグインを実行するためのsystemdサービスユニットを作成します。ユーザーのホームディレクトリに配置し、systemctl --userで管理することを想定しているため、root権限は不要です。

# ファイル名: ~/.config/systemd/user/kubectl-repo-info.service

[Unit]
Description=kubectl repo-info Plugin Service
Documentation=https://github.com/your-org/your-kubectl-plugins
Requires=network-online.target
After=network-online.target

[Service]

# Type=oneshot: コマンド実行後、すぐに終了するサービス

Type=oneshot

# ExecStart: 実行するコマンド。フルパスを推奨。


#            Krewがインストールしたプラグインは通常 ~/.krew/bin に配置される。

ExecStart=%h/.krew/bin/kubectl-repo-info kubernetes kubernetes

# User: サービスを実行するユーザー (systemd --userの場合は現在のユーザーがデフォルト)


# Group: サービスを実行するグループ


# 今回はユーザーサービスなので、これらは省略可ですが、明示的に記述することも可能


# User=your_username


# Group=your_groupname


# Environment: 環境変数の設定 (必要に応じて)

Environment="KUBECONFIG=/home/%u/.kube/config"

# StandardOutput/Error: ログの出力先。journaldに送られる

StandardOutput=journal
StandardError=journal

# WorkingDirectory: 実行時のワーキングディレクトリ (必要に応じて)

WorkingDirectory=%h

[Install]
WantedBy=default.target

補足: %hはユーザーのホームディレクトリ、%uはユーザー名に自動的に展開されます。

2.3.2. systemd Timerファイル (.timer)

次に、上記サービスを定期的に起動するためのsystemdタイマーユニットを作成します。

# ファイル名: ~/.config/systemd/user/kubectl-repo-info.timer

[Unit]
Description=Run kubectl repo-info Plugin Daily
Requires=kubectl-repo-info.service

[Timer]

# OnCalendar: タイマーの起動スケジュールを設定。毎日午前3時。

OnCalendar=*-*-* 03:00:00

# AccuracySec: 起動の精度。デフォルトは1分。10秒に設定。

AccuracySec=10s

# Persistent: タイマーが最後に起動するはずだった時刻を記録し、


#              システム停止中にスケジュールされた実行を起動時にキャッチアップする。


#              システムの電源が切れている間にスキップされた実行が、システム起動後に実行される。

Persistent=true

[Install]
WantedBy=timers.target

2.3.3. systemd設定の有効化と起動

UnitとTimerファイルを配置したら、systemdに設定を認識させ、タイマーを有効化します。

#!/bin/bash

set -euo pipefail

echo "systemd設定をリロード中..."

# systemd --user: 現在のユーザーのsystemdインスタンスに指示

systemctl --user daemon-reload || error_exit "Failed to reload systemd user daemon."

echo "kubectl-repo-info.timerを有効化し、起動中..."

# --now: 有効化と同時に起動

systemctl --user enable --now kubectl-repo-info.timer || error_exit "Failed to enable and start timer."

echo "タイマーのステータス確認:"
systemctl --user list-timers --all | grep kubectl-repo-info
echo "---"
echo "systemd設定が完了しました。"

3. 検証

3.1. プラグイン単体テスト

kubectlコマンドからプラグインが正しく呼び出されるか確認します。 プラグインファイルがPATHの通ったディレクトリ（例: ~/.krew/bin）にあることを確認してください。

kubectl repo-info kubernetes kubernetes

# 期待される出力例:


# Fetching repository info for kubernetes/kubernetes...


# {


#   "name": "kubernetes",


#   "description": "Production-Grade Container Orchestration",


#   "stars": 110000,


#   "url": "https://github.com/kubernetes/kubernetes"


# }


# Plugin execution completed.

3.2. Krewによるインストールと管理 (セルフホストの場合)

自作プラグインをKrewで管理する場合、ローカルKrewインデックスにプラグインマニフェストを追加し、インストールをシミュレートします。 Krewの公式インデックスに公開する場合は、Krew Plugin Developer Guideを参照してください。

  1. マニフェストファイルの配置: repo-info.yamlファイルを~/.krew/index/default/ディレクトリにコピーします。これは一時的なテスト用です。 cp repo-info.yaml ~/.krew/index/default/

  2. Krewキャッシュの更新: kubectl krew update

  3. プラグインのインストール: kubectl krew install repo-info これにより、Krewはマニフェストで指定されたURIからバイナリを取得し、~/.krew/binに配置します。

3.3. systemdユニット/タイマーのテスト

  1. サービスの即時実行: タイマーを待たずにサービスを手動で実行し、動作を確認します。 systemctl --user start kubectl-repo-info.service

  2. ログの確認: journalctl --user -u kubectl-repo-info.service プラグインの出力とエラーがログに記録されていることを確認します。 2024年7月29日 03:00:00の実行履歴が表示されるはずです。

  3. タイマーの起動状況確認: systemctl --user list-timers --all kubectl-repo-info.timerがACTIVATED状態であり、NEXT実行時刻が正しく設定されていることを確認します。

4. 運用

4.1. Krewによるプラグインのライフサイクル管理

Krewはkubectlプラグインの運用を大幅に簡素化します。

  • インストール: kubectl krew install <plugin-name>

  • アップグレード: kubectl krew upgrade <plugin-name> (プラグインマニフェストのversionを更新し、バイナリURIとsha256を変更することで、ユーザーはupgradeコマンドで最新版を取得できます)

  • アンインストール: kubectl krew uninstall <plugin-name>

  • 一覧表示: kubectl krew list

4.2. systemdによる定期実行の監視

systemdタイマーで実行されるサービスは、journalctlを使用して簡単に監視できます。

  • 特定のサービスログ: journalctl --user -u kubectl-repo-info.service

  • 直近のログ: journalctl --user -u kubectl-repo-info.service -f (リアルタイム監視)

  • タイマーイベントログ: journalctl --user -u kubectl-repo-info.timer

4.3. 権限分離とセキュリティ

  • 最小特権の原則: プラグインは、その機能に必要な最小限の権限で実行されるべきです。systemdユーザーサービスを利用することで、root権限を必要としない定期実行が可能です。

  • 秘密情報の管理: APIキーや認証情報は、プラグインのスクリプト内に直接書き込むのではなく、環境変数、Kubernetes Secret、あるいは外部のシークレット管理システム（例: HashiCorp Vault）を通じて安全に渡すようにします。

  • 入力検証: ユーザーからの入力（kubectlコマンドの引数）は常に検証し、意図しないコマンドインジェクションやファイルパス操作を防ぎます。

  • 依存関係の脆弱性: curlやjqのような外部ツールは、常に最新のセキュリティパッチが適用されていることを確認してください。

5. トラブルシュート

5.1. プラグインが実行できない (Command not found)

  • PATHの確認: echo $PATH で~/.krew/binが含まれているか確認します。含まれていない場合、Krewのインストール指示に従い、シェル設定ファイル（例: ~/.bashrc, ~/.zshrc）にパスを追加し、シェルを再起動またはsourceコマンドで再読み込みします。

  • 実行権限: chmod +x ~/.krew/bin/kubectl-repo-info のように実行権限があるか確認します。

  • プラグイン名: ファイル名がkubectl-で始まっているか、そしてkubectlコマンドの引数と一致しているか確認します（例: kubectl-repo-info なら kubectl repo-info）。

5.2. プラグインの実行エラー

  • スクリプト構文エラー: シェルスクリプトのset -euo pipefailにより、エラー箇所が特定されやすくなります。エラーメッセージを注意深く読み、修正します。

  • 依存ツール不足: curlやjqがインストールされているか、PATHが通っているか確認します。

  • APIエラー: curlの出力やHTTPステータスコードを確認します。--fail-with-bodyオプションはデバッグに役立ちます。ネットワーク接続、APIキー、レート制限なども確認します。

  • JSONパースエラー: jqの-eオプションにより、パース失敗時にエラーが返されます。JSONデータが想定通りか、jqのフィルタが正しいか確認します。

5.3. systemdタイマーが動作しない

  • タイマーの有効化: systemctl --user is-enabled kubectl-repo-info.timer でenabledと表示されるか確認します。disabledであればsystemctl --user enable --now kubectl-repo-info.timerで有効化します。

  • サービスのリロード: systemctl --user daemon-reload を実行し、設定ファイルの変更が反映されていることを確認します。

  • ログの確認: journalctl --user -u kubectl-repo-info.timer と journalctl --user -u kubectl-repo-info.service でエラーがないか確認します。

  • スケジュール設定: OnCalendarの設定が正しいか確認します。タイムゾーンの問題がないかも考慮します。

6. まとめ

、kubectlプラグインの開発から、Krewによる管理、そしてsystemdを用いた定期実行までの包括的な手順を解説しました。

graph TD
    A["プラグイン本体開発"] --> B{"Krewマニフェスト作成"};
    B --> C["Krewインデックス登録|任意|"];
    C --> D["ユーザーによるKrewインストール|kubectl krew install|"];
    D --> E["systemd Unit作成"];
    E --> F["systemd Timer設定"];
    F --> G["定期実行/監視"];

  • プラグイン開発: 堅牢なBashスクリプト作成のベストプラクティス（set -euo pipefail, trap, mktemp -d）と、curlおよびjqを用いた具体的な処理方法を示しました。

  • Krewによる管理: プラグインの発見、インストール、アップグレードを簡素化するKrewの活用法と、プラグインマニフェストの作成方法を説明しました。

  • systemdによる自動化: systemd.serviceとsystemd.timerファイルを用いて、ユーザー権限でプラグインを定期実行する仕組みを構築しました。

  • セキュリティと運用: 最小特権の原則、ログ監視、および一般的なトラブルシューティングのポイントも網羅しました。

これらの技術を組み合わせることで、Kubernetes環境におけるオペレーションを効率化し、より安全で自動化されたDevOpsワークフローを実現できるでしょう。

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

タイトルとURLをコピーしました