DOCSEARCHbyAlgolia
Submit Docs

Quarkus Operator SDK (QOSDK)

repository·main·Indexed 40 days ago

https://github.com/quarkiverse/quarkus-operator-sdk

A Quarkus extension that integrates the Java Operator SDK (JOSDK) with Quarkus, enabling developers to write Kubernetes operators in Java. It provides tools for bootstrapping projects, generating Custom Resource Definitions (CRDs), and interactive development via Dev Mode commands like `qosdk api` and `qosdk versions`. The SDK supports OLM (Operator Lifecycle Manager) bundle generation and native binary compilation.

Tokens
13.1K
Snippets
41
Records
56
Agent score
96%

What's inside QOSDK

  1. Core features and capabilities of QOSDK

    main

    The Quarkus Operator SDK (QOSDK) provides several automated features for developing Kubernetes operators:

    Developer Experience

    • Automatic Boilerplate: Automatically generates the main class; you only need to implement Reconciler classes.
    • Automatic Registration: Reconcilers are automatically registered and started.
    • Native Support: Automatically configures support for native compilation.
    • Dev Mode: Provides a live-coding experience where the operator reloads automatically upon code changes.

    Configuration and CDI

    • Build-time Configuration: Processes configuration at build time to catch issues early.
    • Runtime Overrides: Allows overriding configuration via application properties.
    • CDI Integration:
      • The Kubernetes/OpenShift client is automatically injectable.
      • The Operator bean is available for injection.
      • Reconciler implementations, DependentResource implementations, and Workflow conditions are all available as CDI beans.

    Kubernetes and CRD Support

    • Automatic CRD Generation: Generates CRDs for all CustomResource implementations used by reconcilers.
    • Automatic Application: In Dev Mode and during tests, CRDs are automatically applied to the cluster when changes are detected.
    • RBAC and Descriptors: Automatically generates Kubernetes descriptors and RBACs, leveraging configuration metadata (e.g., for dependent resources).

  2. Control bundle metadata with CSVMetadata

    main

    The quarkus-operator-sdk-bundle-generator extension attempts to infer metadata, but you can explicitly control it using the io.quarkiverse.operatorsdk.annotations.CSVMetadata annotation from the quarkus-operator-sdk-annotations module.

    Single Bundle (Default)

    By default, all reconcilers in a project are generated as part of a single bundle using a name inferred from the project name.

    Multiple Bundles

    To split reconcilers into different bundles, you can use the io.quarkiverse.operatorsdk.annotations.SharedCSVMetadata marker interface:

    1. Create a class that implements SharedCSVMetadata.
    2. Annotate that class with @CSVMetadata and specify a unique bundleName.
    3. Annotate your reconciler classes with @CSVMetadata using the same name as the SharedCSVMetadata class. This assigns them to that specific bundle and allows them to share the metadata defined in the marker class.

    Note: If a SharedCSVMetadata implementation does not specify a bundle name, its metadata will be shared among all reconcilers that do not have an explicit bundle name assigned.

  4. Format Duration values

    main

    When configuring properties that require a java.time.Duration (like max-reconciliation-interval), you can use the standard ISO-8601 format or a simplified shorthand:

    Shorthand Rules:

    • Number only: Represents seconds (e.g., 30).
    • Number + ms: Represents milliseconds (e.g., 500ms).
    • Number + h, m, or s: Automatically prefixed with PT (e.g., 10m becomes PT10M).
    • Number + d: Automatically prefixed with P (e.g., 1d becomes P1D).

  7. Build and push the Operator Bundle image

    main

    Once the bundle manifests are generated in target/bundle/<operator name>, use the provided bundle.Dockerfile to build the Operator Bundle image. This image contains the Kubernetes manifests and metadata required by OLM.

    JOKE_BUNDLE_IMAGE=<your container registry>/<your container registry namespace>/<bundle image name>:<tag>

docker build -t $JOKE_BUNDLE_IMAGE -f target/bundle/<operator name>/bundle.Dockerfile target/bundle/<operator name>
docker push $JOKE_BUNDLE_IMAGE

  8. Enable Helm chart generation for your operator

    main

    To generate Helm charts for your operator, include the quarkus-helm extension in your project dependencies. When this extension is present, the Quarkus Operator SDK automatically detects it and includes the generated Custom Resource Definitions (CRDs) in the resulting Helm chart.

    No additional configuration is required within the Operator SDK to enable this integration.

    <dependency>
  <groupId>io.quarkiverse.helm</groupId>
  <artifactId>quarkus-helm</artifactId>
  <version>${version.io.quarkiverse.helm}</version>
</dependency>

  10. Quick start: Local development of the MySQL Schema Operator

    main

    To develop and test the operator locally without creating a container image, follow these steps:

    1. Connect to your cluster: Use kubectl or oc to select your target namespace. The operator connects to the cluster/namespace context active when it starts.
    2. Prepare the project: Run mvn -Dquickly from the root directory to build the project and navigate to the sample directory.
    3. Build and generate CRDs: Run mvn package. This generates the required Custom Resource Definitions (CRDs) in target/manifests.
    4. Deploy CRDs: Apply the generated CRDs to your cluster (requires cluster admin privileges):
      kubectl apply -f target/manifests/mysqlschemas.mysql.sample.javaoperatorsdk-v1.yml
    5. Configure MySQL: Access to the MySQL server is configured in application.properties. In dev mode, Quarkus DevServices provides a database automatically.
    6. Launch Dev Mode: Run mvn quarkus:dev to start the operator in development mode.
    7. Test the operator: Deploy a test schema using the provided resource:
      kubectl apply -f src/main/resources/mydb.yml
    8. Cleanup: Delete the schema resource to remove the database and user:
      kubectl delete -f src/main/resources/mydb.yml
    # Build and generate CRDs
mvn package

# Deploy CRDs
kubectl apply -f target/manifests/mysqlschemas.mysql.sample.javaoperatorsdk-v1.yml

# Launch in dev mode
mvn quarkus:dev

# Deploy test schema
kubectl apply -f src/main/resources/mydb.yml

# Cleanup
kubectl delete -f src/main/resources/mydb.yml

  12. Quick start for local operator development

    main

    To develop and test your operator locally without creating container images or deploying to a cluster, follow these steps:

    1. Connect to your cluster: Use kubectl or oc to connect to your target Kubernetes cluster and select the appropriate namespace.
    2. Build the project: From the parent directory, run the Maven command with the -Dquickly flag to build locally and move to the sample directory.
    3. Generate CRDs: Run mvn package to build the operator. This generates CRDs in target/kubernetes/.
      • Note on versions: By default, v1 is generated. To generate v1beta1 for older clusters, use -Dquarkus.operator-sdk.crd.versions=v1beta1,v1.
    4. Apply CRDs: If quarkus.operator-sdk.crd.apply=true and quarkus.operator-sdk.crd.generate-all=true are set (as in the sample), CRDs will be applied automatically. Otherwise, apply them manually from target/kubernetes/.
    5. Run in Dev Mode: Launch the application using mvn quarkus:dev.
    6. Test with a Request: Apply a test request (e.g., kubectl apply -f src/main/k8s/jokerequest.yml). The operator will process the request and create the corresponding resource (e.g., a Joke resource).
    # 1. Build project locally
# Run this in the parent directory
mvn -Dquickly -Dquarkus.operator-sdk.crd.apply=true

# 2. Build operator and generate CRDs
mvn package

# 3. Launch dev mode
mvn quarkus:dev

# 4. Deploy a test request
kubectl apply -f src/main/k8s/jokerequest.yml

# 5. Verify results
kubectl get jokes