How to work with custom resources

The official Kubernetes documentation describes an example of creating a CronTab resource. On this page will take the same example and access the custom resource with zio-k8s.

Custom resource definition

Start with an empty sbt project. The first step is to create the custom resource definition as a standard Kubernetes CRD YAML. We can take the example from the above linked documentation page and put it in a subfolder, for example crds/crontab.yaml:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  # name must match the spec fields below, and be in the form: <plural>.<group>
  name: crontabs.stable.example.com
spec:
  # group name to use for REST API: /apis/<group>/<version>
  group: stable.example.com
  # list of versions supported by this CustomResourceDefinition
  versions:
    - name: v1
      # Each version can be enabled/disabled by Served flag.
      served: true
      # One and only one version must be marked as the storage version.
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                cronSpec:
                  type: string
                image:
                  type: string
                replicas:
                  type: integer
  # either Namespaced or Cluster
  scope: Namespaced
  names:
    # plural name to be used in the URL: /apis/<group>/<version>/<plural>
    plural: crontabs
    # singular name to be used as an alias on the CLI and for display
    singular: crontab
    # kind is normally the CamelCased singular type. Your resource manifests use this.
    kind: CronTab
    # shortNames allow shorter string to match your resource on the CLI
    shortNames:
    - ct

This can be applied to a Kubernetes cluster with kubectl:

kubectl apply -f crds/crontab.yaml

or with Scala code using the CustomResourceDefinitions resource provided by zio-k8s-client. The operator library provides a helper function to register custom resoure definitions on startup.

Code generator

The next step is to add zio-k8s-crd to the list of sbt plugins, in project/plugins.sbt:

addSbtPlugin("com.coralogix" %% "zio-k8s-crd" % "3.1.0"

and in the build.sbt enable code generation from the crontab.yml file:

externalCustomResourceDefinitions := Seq(
  file("crds/crontab.yaml"),
)

enablePlugins(K8sCustomResourceCodegenPlugin)

Using the generated client

The sbt plugin generates code that has exactly the same structure as the built-in Kubernetes resources. There will be a client module with live and test layers for each custom resource.

import com.coralogix.zio.k8s.client.com.example.stable.v1.crontabs

crontabs.get("ct1", K8sNamespace.default)

The models for custom resources are generated by Guardrail, so everything that guardrail supports can be used in the OpenAPI specification.