Skip to content

Latest commit

 

History

History
477 lines (377 loc) · 13.8 KB

CRD-generator.md

File metadata and controls

477 lines (377 loc) · 13.8 KB
Raw

CRD generation

Quick start

Import the Annotation Processor into your build.

with Maven:

<dependency>
    <groupId>io.fabric8</groupId>
    <artifactId>crd-generator-apt</artifactId>
    <scope>provided</scope>
</dependency>

with Gradle:

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

Now you can define a class that extends io.fabric8.kubernetes.client.CustomResource and the corresponding CRD is generated in the folder: target/classes/META-INF/fabric8

For example, for code similar to:

@Group("org.example")
@Version("v1alpha1")
@ShortNames("ex")
public class Example extends CustomResource<ExampleSpec, ExampleStatus> implements Namespaced {}

public class ExampleSpec {
  int someValue;
}

public class ExampleStatus {
  boolean error;
  String message;
}

Running the compile task will generate 2 files target/classes/META-INF/fabric8/examples.org.example-v1.yml and target/classes/META-INF/fabric8/examples.org.example-v1beta1.yml, the file name is calculated as <plural>.<group>-<CRD spec version>.yml.

The content of the v1 looks similar to:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: examples.org.example
spec:
  group: org.example
  names:
    kind: Example
    plural: examples
    shortNames:
    - ex
    singular: example
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        properties:
          spec:
            properties:
              someValue:
                type: integer
            type: object
          status:
            properties:
              error:
                type: boolean
              message:
                type: string
            type: object
        type: object
    served: true
    storage: true
    subresources:
      status: {}

Features

com.fasterxml.jackson.annotation.JsonProperty

If a field or one of its accessors is annotated with com.fasterxml.jackson.annotation.JsonProperty

public class ExampleSpec {
  @JsonProperty("myValue")
  int someValue;
}

The generated field in the CRD will be named after the value provided in the annotation instead of using the default name derived from the field name, such as:

          spec:
            properties:
              myValue:
                type: integer
            type: object

com.fasterxml.jackson.annotation.JsonPropertyDescription

If a field or one of its accessors is annotated with com.fasterxml.jackson.annotation.JsonPropertyDescription

public class ExampleSpec {
  @JsonPropertyDescription("This is some value")
  int someValue;
}

The generated field in the CRD will preserve the provided description, such as:

          spec:
            properties:
              someValue:
                description: This is some value
                type: integer
            type: object

com.fasterxml.jackson.annotation.JsonIgnore

If a field or one of its accessors is annotated with com.fasterxml.jackson.annotation.JsonIgnore

public class ExampleSpec {
  @JsonIgnore
  int someValue;
}

The field will be skipped in the generated CRD and will not appear in the schema for this type, such as:

          spec:
            type: object

io.fabric8.generator.annotation.Min

If a field or one of its accessors is annotated with io.fabric8.generator.annotation.Min

public class ExampleSpec {
  @Min(-1)
  int someValue;
}

The field will have the minimum property in the generated CRD, such as:

          spec:
            properties:
              someValue:
                minimum: -1.0
                type: integer
            required:
            - someValue
            type: object

io.fabric8.generator.annotation.Max

If a field or one of its accessors is annotated with io.fabric8.generator.annotation.Max

public class ExampleSpec {
  @Max(1)
  int someValue;
}

The field will have the maximum property in the generated CRD, such as:

          spec:
            properties:
              someValue:
                maximum: 1.0
                type: integer
            required:
            - someValue
            type: object

io.fabric8.generator.annotation.Pattern

If a field or one of its accessors is annotated with io.fabric8.generator.annotation.Pattern

public class ExampleSpec {
  @Pattern("\\b[1-9]\\b")
  String someValue;
}

The field will have the pattern property in the generated CRD, such as:

          spec:
            properties:
              someValue:
                pattern: "\\b[1-9]\\b"
                type: string
            required:
            - someValue
            type: object

io.fabric8.generator.annotation.Nullable

If a field or one of its accessors is annotated with io.fabric8.generator.annotation.Nullable

public class ExampleSpec {
  @Nullable
  String someValue;
}

The field will have the nullable property in the generated CRD, such as:

          spec:
            properties:
              someValue:
                nullable: true
                type: string
            required:
            - someValue
            type: object

io.fabric8.generator.annotation.Required

If a field or one of its accessors is annotated with io.fabric8.generator.annotation.Required

public class ExampleSpec {
  @Required
  int someValue;
}

The field will be marked as required in the generated CRD, such as:

          spec:
            properties:
              someValue:
                type: integer
            required:
            - someValue
            type: object

io.fabric8.crd.generator.annotation.SchemaFrom

If a field or one of its accessors is annotated with io.fabric8.crd.generator.annotation.SchemaFrom

public class ExampleSpec {
  @SchemaFrom(ExampleStatus.class)
  int someValue;
}

The CRD generator will substitute the default type inferred from the field and replace it by the computed schema associated with the Java class provided as a value of the SchemaFrom annotation, as seen below, where ExampleStatus is the class defined in the example above:

          spec:
            properties:
              someValue:
                properties:
                  error:
                    type: boolean
                  message:
                    type: string
                type: object
            type: object

io.fabric8.crd.generator.annotation.SchemaSwap

If a class is annotated with io.fabric8.crd.generator.annotation.SchemaSwap

@SchemaSwap(originalType = ExampleSpec.class, fieldName = "someValue", targetType = ExampleStatus.class)
public class Example extends CustomResource<ExampleSpec, ExampleStatus> implements Namespaced {}

The CRD generator will perform the same substitution as a SchemaFrom annotation with value equal to targetType was placed on the field named fieldName in the originalType class:

          spec:
            properties:
              someValue:
                properties:
                  error:
                    type: boolean
                  message:
                    type: string
                type: object
            type: object

The name of the field is restricted to the original fieldName and should be backed by a matching concrete field of the matching class. Getters, setters, and constructors are not taken into consideration.

SchemaSwaps cannot currently be nested - if a more deeply nested class contains a swap for the same class and field, an exception will be thrown.

The ScheamSwap annotation has an optional depth property, which is for advanced scenarios involving cyclic references. Since CRDs cannot directly represent cycles, the depth property may be used to control an unrolling of the representation in your CRD. A depth of 0, the default, performs the swap on the field without the originalType appearing in your CRD. A depth of n will allow the originalType to appear in the CRD up to a nesting depth of n, with the specified field at the nth level terminated by the targetType.

Generating x-kubernetes-preserve-unknown-fields: true

If a field or one of its accessors is annotated with com.fasterxml.jackson.annotation.JsonAnyGetter/com.fasterxml.jackson.annotation.JsonAnySetter or the field type is com.fasterxml.jackson.databind.JsonNode

public class ExampleSpec {
  JsonNode someValue;

  @JsonAnyGetter
  JsonNode getSomeValue() {
    return someValue;
  }

  @JsonAnySetter
  void setSomeValue(JsonNode value) {
    this.someValue = value;
  }
}

Corresponding x-kubernetes-preserve-unknown-fields: true will be generated in the output CRD, such as:

          spec:
            properties:
              someValue:
                type: object
                x-kubernetes-preserve-unknown-fields: true
            type: object
            x-kubernetes-preserve-unknown-fields: true

You can also annotate a field with io.fabric8.crd.generator.annotation.PreserveUnknownFields:

interface ExampleInterface {}

public class ExampleSpec {
    @PreserveUnknownFields
    ExampleInterface someValue;
}

will be generated as:

          spec:
            properties:
              someValue:
                type: object
                x-kubernetes-preserve-unknown-fields: true
            type: object

io.fabric8.crd.generator.annotation.Annotations

If a custom resource class is annotated with io.fabric8.crd.generator.annotation.Annotations

@Annotations({ "one=1", "two=2" })
public class Example extends CustomResource<ExampleSpec, ExampleStatus> implements Namespaced {}

The CRD generator will add the additional annotations:

          metadata:
            name: examples.org.example
            annotations:
              one: "1"
              two: "2"
          spec:
            ...

io.fabric8.crd.generator.annotation.Labels

If a custom resource class is annotated with io.fabric8.crd.generator.annotation.Labels

@Labels({ "three=3", "four=4" })
public class Example extends CustomResource<ExampleSpec, ExampleStatus> implements Namespaced {}

The CRD generator will add the additional labels:

          metadata:
            name: examples.org.example
            labels:
              four: "4"
              three: "3"
          spec:
            ...

Features cheatsheet

Annotation Description
com.fasterxml.jackson.annotation.JsonProperty The field is named after the provided value instead of looking up the java field name
com.fasterxml.jackson.annotation.JsonPropertyDescription The provided text is be embedded in the description of the field
com.fasterxml.jackson.annotation.JsonIgnore The field is ignored
io.fabric8.crd.generator.annotation.PreserveUnknownFields The field have x-kubernetes-preserve-unknown-fields: true defined
com.fasterxml.jackson.annotation.JsonAnyGetter The corresponding object have x-kubernetes-preserve-unknown-fields: true defined
com.fasterxml.jackson.annotation.JsonAnySetter The corresponding object have x-kubernetes-preserve-unknown-fields: true defined
io.fabric8.generator.annotation.Min The field defines a validation min
io.fabric8.generator.annotation.Max The field defines a validation max
io.fabric8.generator.annotation.Pattern The field defines a validation pattern
io.fabric8.generator.annotation.Nullable The field is marked as nullable
io.fabric8.generator.annotation.Required The field is marked as required
io.fabric8.crd.generator.annotation.SchemaFrom The field type for the generation is the one coming from the annotation
io.fabric8.crd.generator.annotation.SchemaSwap Similar to SchemaFrom, but can be applied at any point in the class hierarchy
io.fabric8.crd.generator.annotation.Annotations Additional annotations in metadata
io.fabric8.crd.generator.annotation.Labels Additional labels in metadata

A field of type com.fasterxml.jackson.databind.JsonNode is encoded as an empty object with x-kubernetes-preserve-unknown-fields: true defined.

Experimental

Generate CRDs in parallel

It's possible to speed up the CRDs generation by using parallel computation. Please note that this feature is experimental, and it may lead to unexpected results.

To enable it, you need to set the io.fabric8.crd.generator.parallel property to true in the processor.

with Maven:

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <compilerArgs>
      <arg>-Aio.fabric8.crd.generator.parallel=true</arg>
    </compilerArgs>
  </configuration>
</plugin>

with Gradle:

tasks.withType(JavaCompile) {
  options.compilerArgs += ["-Aio.fabric8.crd.generator.parallel=true"]
}