Operator のテストと配布 — envtest・e2e・OLM・バンドルパッケージング

              /\
             /  \        e2e (kind / 実クラスタ)
            /    \       - 少数、遅い、コスト高
           /------\      - 全体フロー、実 kubelet・CNI を検証
          /        \
         /          \    envtest 統合テスト
        /            \   - 中程度、実 apiserver+etcd
       /              \  - reconcile <-> API の相互作用を検証
      /----------------\
     /                  \ unit reconcile テスト
    /                    \- 多数、速い、コスト低
   /                      \- fake client でロジック単位の検証
  /________________________\

# 特定の Kubernetes バージョン向け envtest バイナリをインストール
go run sigs.k8s.io/controller-runtime/tools/setup-envtest@latest use 1.36.x

# インストールパスを環境変数として公開
export KUBEBUILDER_ASSETS=$(setup-envtest use 1.36.x -p path)

package controller

import (
	"context"
	"path/filepath"
	"testing"

	. "github.com/onsi/ginkgo/v2"
	. "github.com/onsi/gomega"

	"k8s.io/client-go/kubernetes/scheme"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/envtest"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"

	webappv1 "example.com/guestbook-operator/api/v1"
)

var (
	cfg       *rest.Config
	k8sClient client.Client
	testEnv   *envtest.Environment
	ctx       context.Context
	cancel    context.CancelFunc
)

func TestControllers(t *testing.T) {
	RegisterFailHandler(Fail)
	RunSpecs(t, "Controller Suite")
}

var _ = BeforeSuite(func() {
	logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))

	ctx, cancel = context.WithCancel(context.TODO())

	By("テスト環境のブートストラップ")
	testEnv = &envtest.Environment{
		CRDDirectoryPaths:     []string{filepath.Join("..", "..", "config", "crd", "bases")},
		ErrorIfCRDPathMissing: true,
	}

	var err error
	cfg, err = testEnv.Start()
	Expect(err).NotTo(HaveOccurred())
	Expect(cfg).NotTo(BeNil())

	Expect(webappv1.AddToScheme(scheme.Scheme)).To(Succeed())

	k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
	Expect(err).NotTo(HaveOccurred())
	Expect(k8sClient).NotTo(BeNil())

	mgr, err := ctrl.NewManager(cfg, ctrl.Options{Scheme: scheme.Scheme})
	Expect(err).NotTo(HaveOccurred())

	err = (&GuestbookReconciler{
		Client: mgr.GetClient(),
		Scheme: mgr.GetScheme(),
	}).SetupWithManager(mgr)
	Expect(err).NotTo(HaveOccurred())

	go func() {
		defer GinkgoRecover()
		Expect(mgr.Start(ctx)).To(Succeed())
	}()
})

var _ = AfterSuite(func() {
	cancel()
	By("テスト環境の後始末")
	Expect(testEnv.Stop()).To(Succeed())
})

var _ = Describe("Guestbook コントローラ", func() {
	const (
		resourceName = "test-guestbook"
		namespace    = "default"
	)

	Context("Guestbook リソースを reconcile するとき", func() {
		It("Deployment を作成し Ready 状態として表示すべき", func() {
			By("Guestbook オブジェクトの作成")
			gb := &webappv1.Guestbook{
				ObjectMeta: metav1.ObjectMeta{
					Name:      resourceName,
					Namespace: namespace,
				},
				Spec: webappv1.GuestbookSpec{
					Replicas: 3,
					Image:    "nginx:1.27",
				},
			}
			Expect(k8sClient.Create(ctx, gb)).To(Succeed())

			By("コントローラが Deployment を作るか確認")
			deployKey := types.NamespacedName{Name: resourceName, Namespace: namespace}
			createdDeploy := &appsv1.Deployment{}
			Eventually(func() error {
				return k8sClient.Get(ctx, deployKey, createdDeploy)
			}, time.Second*10, time.Millisecond*250).Should(Succeed())

			Expect(*createdDeploy.Spec.Replicas).To(Equal(int32(3)))

			By("所有参照が正しく設定されているか確認")
			Expect(createdDeploy.OwnerReferences).To(HaveLen(1))
			Expect(createdDeploy.OwnerReferences[0].Kind).To(Equal("Guestbook"))
		})
	})
})

package controller

import (
	"context"
	"testing"

	appsv1 "k8s.io/api/apps/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/types"
	"sigs.k8s.io/controller-runtime/pkg/client/fake"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"

	webappv1 "example.com/guestbook-operator/api/v1"
)

func TestReconcile_CreatesDeployment(t *testing.T) {
	s := scheme.Scheme
	_ = webappv1.AddToScheme(s)
	_ = appsv1.AddToScheme(s)

	gb := &webappv1.Guestbook{
		ObjectMeta: metav1.ObjectMeta{Name: "gb", Namespace: "ns"},
		Spec:       webappv1.GuestbookSpec{Replicas: 2, Image: "nginx:1.27"},
	}

	cl := fake.NewClientBuilder().
		WithScheme(s).
		WithObjects(gb).
		Build()

	r := &GuestbookReconciler{Client: cl, Scheme: s}

	_, err := r.Reconcile(context.Background(), reconcile.Request{
		NamespacedName: types.NamespacedName{Name: "gb", Namespace: "ns"},
	})
	if err != nil {
		t.Fatalf("reconcile 失敗: %v", err)
	}

	got := &appsv1.Deployment{}
	if err := cl.Get(context.Background(),
		types.NamespacedName{Name: "gb", Namespace: "ns"}, got); err != nil {
		t.Fatalf("Deployment が作成されていない: %v", err)
	}
	if *got.Spec.Replicas != 2 {
		t.Errorf("replicas 期待値 2、実際 %d", *got.Spec.Replicas)
	}
}

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  name: guestbook-operator.v0.2.0
  namespace: placeholder
spec:
  displayName: Guestbook Operator
  version: 0.2.0
  replaces: guestbook-operator.v0.1.0
  maturity: stable
  installModes:
    - type: OwnNamespace
      supported: true
    - type: SingleNamespace
      supported: true
    - type: MultiNamespace
      supported: false
    - type: AllNamespaces
      supported: true
  customresourcedefinitions:
    owned:
      - name: guestbooks.webapp.example.com
        version: v1
        kind: Guestbook
  install:
    strategy: deployment
    spec:
      deployments:
        - name: guestbook-controller-manager
          spec:
            replicas: 1

bundle/
|-- manifests/
|   |-- guestbook-operator.clusterserviceversion.yaml
|   |-- webapp.example.com_guestbooks.yaml
|-- metadata/
|   |-- annotations.yaml
|-- bundle.Dockerfile

# CSV のスキャフォールドとバンドルマニフェストの生成
operator-sdk generate kustomize manifests
make bundle VERSION=0.2.0

# バンドルイメージのビルドとプッシュ
make bundle-build bundle-push BUNDLE_IMG=quay.io/example/guestbook-bundle:v0.2.0

# カタログイメージのビルド(バンドル群をインデックス化)
opm index add \
  --bundles quay.io/example/guestbook-bundle:v0.2.0 \
  --tag quay.io/example/guestbook-catalog:latest

  stable チャネルのアップグレードグラフ

  v0.1.0 --replaces-- v0.2.0 --replaces-- v0.3.0
                                              |
                                          skips: v0.2.1 (欠陥バージョン)
                                              |
                                              v
  v0.4.0 --skipRange ">=0.1.0 <0.4.0"-- v0.5.0

  インストール時: OLM はチャネルの head(最新)を見つけ、
                  replaces チェーンを段階的にたどるか、
                  skipRange で一気に head までジャンプする

# CSV のアノテーションで skipRange を指定
metadata:
  name: guestbook-operator.v0.5.0
  annotations:
    olm.skipRange: '>=0.1.0 <0.5.0'
spec:
  replaces: guestbook-operator.v0.4.0
  skips:
    - guestbook-operator.v0.2.1

  OperatorHub 配布フロー

  開発者 --PR--> community-operators リポジトリ
                       |
                       | CI: バンドル検証、CSV lint、
                       |     インストールモード検査、アップグレード経路確認
                       v
                  マージ --> カタログイメージに反映
                              |
                              v
  ユーザークラスタの OLM --> OperatorHub UI に表示
                              |
                              v
                       Subscription の作成でインストール

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: guestbook-operator
  namespace: operators
spec:
  channel: stable
  name: guestbook-operator
  source: operatorhubio-catalog
  sourceNamespace: olm
  installPlanApproval: Automatic

// 変換 webhook: v1beta1 <-> v1 変換の例
func (src *GuestbookV1Beta1) ConvertTo(dstRaw conversion.Hub) error {
	dst := dstRaw.(*GuestbookV1)
	dst.ObjectMeta = src.ObjectMeta
	dst.Spec.Replicas = src.Spec.Count // フィールド名変更を吸収
	dst.Spec.Image = src.Spec.Image
	return nil
}

func (dst *GuestbookV1Beta1) ConvertFrom(srcRaw conversion.Hub) error {
	src := srcRaw.(*GuestbookV1)
	dst.ObjectMeta = src.ObjectMeta
	dst.Spec.Count = src.Spec.Replicas
	dst.Spec.Image = src.Spec.Image
	return nil
}

// reconcile 関数のすぐ上に RBAC マーカーを宣言
//+kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks,verbs=get;list;watch;create;update;patch;delete
//+kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks/status,verbs=get;update;patch
//+kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks/finalizers,verbs=update
//+kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
func (r *GuestbookReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	// reconcile ロジック
	return ctrl.Result{}, nil
}

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: manager-role
rules:
  - apiGroups: ['webapp.example.com']
    resources: ['guestbooks']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']
  - apiGroups: ['webapp.example.com']
    resources: ['guestbooks/status']
    verbs: ['get', 'update', 'patch']
  - apiGroups: ['apps']
    resources: ['deployments']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'patch', 'delete']

// メトリクスサーバを認証・認可フィルタで保護
mgr, err := ctrl.NewManager(cfg, ctrl.Options{
	Scheme: scheme,
	Metrics: metricsserver.Options{
		BindAddress:    ":8443",
		SecureServing:  true,
		FilterProvider: filters.WithAuthenticationAndAuthorization,
	},
})

  インストールモード別の監視範囲

  OwnNamespace        SingleNamespace      AllNamespaces
  +----------+        +----------+         +------------------+
  | ns-a     |        | operator |         | クラスタ全体     |
  | [op][cr] |        +----+-----+         | +----++----++---+ |
  +----------+             | watch         | |ns-a||ns-b||...| |
                           v               | +----++----++---+ |
                      +----------+          +--------+---------+
                      | ns-b     |              op watch all
                      | [cr]     |
                      +----------+

mgr, err := ctrl.NewManager(cfg, ctrl.Options{
	Scheme: scheme,
	Cache: cache.Options{
		DefaultNamespaces: map[string]cache.Config{
			"team-a-workloads": {},
		},
	},
})