Java Operator SDK

Java Operator SDK

  • 生成项目骨架
  • 快速入门
  • 模式和最佳实践
  • 使用示例Operators
    • 实现示例Operator
    • Quarkus
    • Spring Boot

Operators 代表Kubernetes管理集群和非集群资源。这个Java Operator SDK (JOSDK) 旨在通过使用一个对Java开发人员来说应该感觉自然的API,使编写Kubernetes操作员变得尽可能容易,并且不必担心许多低级细节,因为SDK会自动处理。

生成项目骨架

该项目包括一个Maven插件,用于生成项目的骨架:

mvn io.javaoperatorsdk:bootstrapper:[version]:create 
-DprojectGroupId=org.acme 
-DprojectArtifactId=getting-started

这个命令使用了Java Operator SDK的bootstrapper插件来创建一个项目的骨架。具体命令是mvn io.javaoperatorsdk:bootstrapper:[version]:create -DprojectGroupId=org.acme -DprojectArtifactId=getting-started

其中[version]是指Java Operator SDK的版本号,-DprojectGroupId=org.acme指定了项目的groupId为org.acme-DprojectArtifactId=getting-started指定了项目的artifactId为getting-started

运行这个命令后,bootstrapper插件会自动生成一个基本的项目结构,包括Maven的pom.xml文件和一些示例代码,以便你可以开始编写Kubernetes操作员。这个骨架项目可以作为一个起点,你可以根据需要进行修改和扩展。

快速入门

使用SDK的最简单方法是启动并执行我们的示例之一。有一个专门的页面来描述如何开始。

以下是开发代码并将operator部署到Kubernetes集群的主要步骤。在samples/mysql-schema/目录下可以找到更详细和具体的版本。

  • 配置kubectl以与您选择的Kubernetes集群一起使用。
  • 应用自定义资源定义(Custom Resource Definition)。
  • 在根目录下使用mvn install编译整个项目(包括框架和示例)。
  • 运行您选择的示例的主类,并查看示例的README文件以了解其功能。在本地运行时,框架将使用您的Kubernetes客户端配置(在~/.kube/config中)建立与集群的连接。这就是为什么提前设置kubectl非常重要。
  • 您可以在本地开发模式下使用这个代码进行测试。
  • 构建Docker镜像并将其推送到镜像仓库。
  • 应用RBAC配置。
  • 应用部署配置。
  • 验证operator是否正在运行。请不要再在本地运行它,以避免处理来自集群API服务器的事件时发生冲突。

模式和最佳实践

本文档介绍了构建和运行操作员的模式和最佳实践,以及如何使用Java Operator SDK (JOSDK)实现它们。请参阅Operator SDK中的最佳实践。

实现Reconciler

始终协调所有资源

协调可以由多个来源的事件触发。检查事件并只协调控制器管理的相关资源或资源子集可能很诱人。然而,这被认为是操作员的反模式,因为Kubernetes的分布式性质使得很难确保始终接收到所有事件。如果由于某种原因,您的操作员没有接收到一些事件,如果您不协调整个状态,您可能会根据关于集群状态的不适当假设进行操作。这就是为什么始终协调所有资源很重要,无论多么诱人只考虑子集。幸运的是,JOSDK尽可能地使其易于使用和高效,通过提供智能缓存来避免过度访问Kubernetes API服务器,并确保仅在需要时触发您的调和器。

由于在业界对这个话题有共识,JOSDK从框架的第2个版本开始不再提供Reconciler实现中的事件访问。

事件源和缓存

如上所述,在协调期间,最佳实践是协调控制器管理的所有相关资源。这意味着我们希望将期望状态与集群的实际状态进行比较。直接从Kubernetes API服务器读取资源的实际状态意味着会产生很大的负载。因此,通常的做法是为相关资源创建一个监视器,并缓存其最新状态。这是使用Informer模式完成的。在Java Operator SDK中,informer被封装在EventSource中,以将其集成到框架的事件系统中。这是通过InformerEventSource类实现的。

仅当实际资源已经在缓存中时,才会将新事件传播到Reconciler。因此,Reconciler实现只需要将期望状态与由缓存资源提供的观察到的状态进行比较。如果在缓存中找不到资源,则需要创建该资源。如果实际状态与期望状态不匹配,则需要更新该资源。

幂等性

由于在触发Reconciler时应协调所有资源,并且在任何给定资源上可以多次触发协调,特别是在使用重试策略时,因此Reconciler实现必须是幂等的,这意味着相同的观察到的状态应该产生完全相同的结果。这也意味着操作员通常应以无状态方式运行。幸运的是,由于操作员通常管理声明性资源,因此通常很容易确保幂等性。

同步或异步方式处理资源

根据您的用例,您的协调逻辑可能需要等待相当长的时间,而操作员等待资源达到其期望状态。例如,您的Reconciler可能需要等待Pod准备就绪,然后再执行其他操作。可以通过同步或异步方式来解决此问题。

异步方式是仅在Reconciler确定无法在此时完成其全部逻辑时退出协调逻辑。这将释放资源以处理其他主资源事件。但是,这需要放置足够的事件源以监视操作员等待的所有资源的状态更改。当正确执行此操作时,任何状态更改都将再次触发Reconciler,它将有机会完成其处理。

同步方式是定期轮询资源的状态,直到它们达到所需状态。如果在您的Reconciler实现的协调方法的上下文中执行此操作,这将阻止当前线程,可能需要很长时间。因此,通常建议使用异步处理方式。

为什么要自动重试?

默认情况下,自动重试已启用,并且可以根据您的需求进行配置。虽然完全关闭此功能是可能的,但我们建议不要这样做。为您的Reconciler配置自动重试的主要原因是由于Kubernetes的分布式性质,错误经常发生:瞬态网络错误可以通过自动重试轻松处理。同样,当与Kubernetes资源一起工作时,不同的操作者可能会修改资源,因此在处理Kubernetes资源时可能会发生冲突。这样的冲突通常可以通过再次协调资源来自然地解决。如果自动完成,整个过程可以完全透明地进行。

管理状态

由于Kubernetes资源的声明性本质,仅处理Kubernetes资源的操作员可以以无状态方式运行,即它们不需要维护有关这些资源状态的信息,因为应该可以从其表示中完全重建资源状态(毕竟,这就是声明性的含义)。但是,当处理外部资源时,这通常不再成立,可能需要操作员跟踪此外部状态,以便在发生另一个协调时可用。虽然这样的状态可以放在主资源的状态子资源中,但如果需要跟踪大量状态,则可能很难管理。它也违反了最佳实践,即资源的状态应该表示实际资源状态,而其规范表示期望状态。因此,不建议将不严格表示资源实际状态的状态放入其中。相反,建议将这种状态放入用于此目的的单独资源中,例如Kubernetes Secret或ConfigMap甚至是专用的自定义资源,其结构更容易验证。

在Informer错误和缓存同步超时的情况下停止(或不停止)操作员

可以配置,如果任何Informer错误发生在启动时,操作员是否应停止。默认情况下,如果在启动时出现错误,例如informer没有权限列出目标资源(包括主资源或辅助资源),则操作员将立即停止。通过将上述标志设置为false,可以更改此行为,从而操作员即使某些informer未启动也会启动。在这种情况下-与稍后遇到问题的informer启动时一样-将无限期地使用指数回退重试连接。仅当资源无法反序列化时,操作员才会停止,当前。更改此标志的典型用例是监视控制器的名称空间列表。在某些名称空间中某些资源的权限问题可能存在时,最好启动操作员,以便在处理其他名称空间时可以处理其他名称空间。

stopOnInformerErrorDuringStartup对缓存同步超时行为产生影响。如果为true,则操作员将在缓存同步超时时停止。如果为false,则在超时后,即使一个或多个事件源缓存未同步,控制器也将开始协调资源。

使用示例Operators

我们在目录下提供了一些示例,旨在演示不同场景下使用不同组件的用法,但主要是更真实的示例:

  • webpage: 简单的示例,创建包含HTML代码的自定义资源的NGINX Web服务器。
  • mysql-schema: 管理MySQL数据库中模式的操作员。演示如何管理非Kubernetes资源。
  • tomcat: 具有两个控制器的操作员,管理Tomcat实例和运行在Tomcat中的Web应用程序。这个示例的目的是展示如何管理多个相关的自定义资源和/或更多的控制器。

实现示例Operator

使用Maven将以下依赖项添加到您的项目中:

<dependency>
    <groupId>io.javaoperatorsdkgroupId>
    <artifactId>operator-frameworkartifactId>
    <version>{see https://search.maven.org/search?q=a:operator-framework%20AND%20g:io.javaoperatorsdk for latest version}version>
dependency>

或者,您也可以使用Gradle,但是需要将SDK声明为注解处理器,以便生成控制器和自定义资源类之间的映射关系:

dependencies {
    implementation "io.javaoperatorsdk:operator-framework:${javaOperatorVersion}"
    annotationProcessor "io.javaoperatorsdk:operator-framework:${javaOperatorVersion}"
}

在添加了依赖项后,定义一个主方法来初始化Operator并注册一个控制器。

public class Runner {

    public static void main(String[] args) {
        Operator operator = new Operator();
        operator.register(new WebPageReconciler());
        operator.start();
    }
}

控制器实现业务逻辑,并描述了处理CRD所需的所有类。

@ControllerConfiguration
public class WebPageReconciler implements Reconciler<WebPage> {

    // Return the changed resource, so it gets updated. See javadoc for details.
    @Override
    public UpdateControl<CustomService> reconcile(CustomService resource,
                                                               Context context) {
        // ... your logic ...
        return UpdateControl.patchStatus(resource);
    }
}

一个示例的自定义资源POJO表示

@Group("sample.javaoperatorsdk")
@Version("v1")
public class WebPage extends CustomResource<WebPageSpec, WebPageStatus> implements
        Namespaced {
}

public class WebServerSpec {

    private String html;

    public String getHtml() {
        return html;
    }

    public void setHtml(String html) {
        this.html = html;
    }
}

禁用CustomResource实现的验证

operator默认会查询部署的CRD以检查CustomResource实现是否与集群中已知的匹配。这需要向集群发起额外的查询,并且有时需要提升operator的权限才能从集群中读取CRD。这种验证主要是为了帮助新手operator开发人员入门并避免常见错误。高级用户或生产部署可能希望跳过此步骤。可以通过将CHECK_CRD_ENV_KEY环境变量设置为false来实现。

自动生成CRD
要从您的注解自定义资源类自动生成CRD清单,您只需要将以下依赖项添加到您的项目中(在背景中使用了注解处理器),使用Maven:

<dependency>
    <groupId>io.fabric8groupId>
    <artifactId>crd-generator-aptartifactId>
    <scope>providedscope>
dependency>

或者使用Gradle:

dependencies {
    annotationProcessor 'io.fabric8:crd-generator-apt:'
    ...
}

CRD将在target/classes/META-INF/fabric8目录中生成(如果使用测试范围,则在target/test-classes/META-INF/fabric8目录中生成),其中CRD名称后缀为生成的规范版本。例如,

  • mycrs.java-operator-sdk.io-v1.yml
  • mycrs.java-operator-sdk.io-v1beta1.yml

注意:使用quarkus-operator-sdk扩展的Quarkus用户无需添加任何额外的依赖项来生成他们的CRD,因为扩展本身会处理这个过程。

Quarkus

还提供了一个Quarkus扩展,以便于基于Quarkus的操作员开发。
在您的项目中添加以下依赖项:这个依赖项

<dependency>
    <groupId>io.quarkiverse.operatorsdkgroupId>
    <artifactId>quarkus-operator-sdkartifactId>
    <version>{see https://search.maven.org/search?q=a:quarkus-operator-sdk for latest version}
    version>
dependency>

创建一个应用程序,Quarkus将自动创建和注入一个KubernetesClient(或OpenShiftClient)、Operator、ConfigurationService和ResourceController实例,您的应用程序可以使用它们。下面是您需要编写的最小代码,以使您的操作员和控制器运行起来:

@QuarkusMain
public class QuarkusOperator implements QuarkusApplication {

    @Inject
    Operator operator;

    public static void main(String... args) {
        Quarkus.run(QuarkusOperator.class, args);
    }

    @Override
    public int run(String... args) throws Exception {
        operator.start();
        Quarkus.waitForExit();
        return 0;
    }
}

Spring Boot

您还可以让Spring Boot自动连接您的应用程序并自动注册控制器。
将以下依赖项添加到您的项目中:这个依赖项

<dependency>
    <groupId>io.javaoperatorsdk</groupId>
    <artifactId>operator-framework-spring-boot-starter</artifactId>
    <version>{see https://search.maven.org/search?q=a:operator-framework-spring-boot-starter%20AND%20g:io.javaoperatorsdk for
        latest version}
    </version>
</dependency>

创建应用

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

您还需要一个 @Configuration 来确保您的协调器已注册:

@Configuration
public class Config {

    @Bean
    public WebPageReconciler customServiceController() {
        return new WebPageReconciler();
    }

    @Bean(initMethod = "start", destroyMethod = "stop")
    @SuppressWarnings("rawtypes")
    public Operator operator(List<Reconciler> controllers) {
        Operator operator = new Operator();
        controllers.forEach(operator::register);
        return operator;
    }
}

Spring Boot 测试支持

添加以下依赖项可以让您模拟需要加载 spring 容器的测试操作员,但不需要真正访问 Kubernetes 集群。

<dependency>
    <groupId>io.javaoperatorsdkgroupId>
    <artifactId>operator-framework-spring-boot-starter-testartifactId>
    <version>{see https://search.maven.org/search?q=a:operator-framework-spring-boot-starter%20AND%20g:io.javaoperatorsdk for
        latest version}
    version>
dependency>

模拟operator:

@SpringBootTest
@EnableMockOperator
public class SpringBootStarterSampleApplicationTest {

    @Test
    void contextLoads() {
    }
}

你可能感兴趣的:(日常分享专栏,java,开发语言,Operator,SDK)