Designing an API

In Kubernetes, we have a few rules for how we design APIs. Namely, allserialized fields must be camelCase, so we use JSON struct tags tospecify this. We can also use the omitempty struct tag to mark thata field should be omitted from serialization when empty.

Fields may use most of the primitive types. Numbers are the exception:for API compatibility purposes, we accept two forms of numbers: int32for integers, and resource.Quantity for decimals.

Hold up, what’s a Quantity?

Quantities are a special notation for decimal numbers that have anexplicitly fixed representation that makes them more portable acrossmachines. You’ve probably noticed them when specifying resources requestsand limits on pods in Kubernetes.

They conceptually work similar to floating point numbers: they havea significand, base, and exponent. Their serialize, human readable foruses whole numbers and suffixes to specify values much the way we describecomputer storage.

For instance, the value 2m means 0.002 in decimal notation. 2Kimeans 2048 in decimal, while 2K means 2000 in decimal. If we wantto specify fractions, we switch to a suffix that lets us use a wholenumber: 2.5 is 2500m.

There are two supported bases: 10 and 2 (called decimal and binary,respectively). Decimal base is indicated with “normal” SI suffixes (e.g.M and K), while Binary base is specified in “mebi” notation (e.g. Miand Ki). Think megabytes vsmebibytes.

There’s one other special type that we use: metav1.Time. This functionsidentically to time.Time, except that it has a fixed, portableserialization format.

With that out of the way, let’s take a look at what our CronJob objectlooks like!

Apache License

Licensed under the Apache License, Version 2.0 (the “License”);you may not use this file except in compliance with the License.You may obtain a copy of the License at

  1. http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an “AS IS” BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License. Imports

  3. package v1
  5. import (
  6.     batchv1beta1 "k8s.io/api/batch/v1beta1"
  7.     corev1 "k8s.io/api/core/v1"
  8.     metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
  9. )
  11. // EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
  12. // NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.

First, let’s take a look at our spec. As we discussed before, spec holdsdesired state, so any “inputs” to our controller go here.

Fundamentally a CronJob needs the following pieces:

  • A schedule (the cron in CronJob)

  • A template for the Job to run (thejob in CronJob) We’ll also want a few extras, which will make our users’ lives easier:

  • A deadline for starting jobs (if we miss this deadline, we’ll just wait tillthe next scheduled time)

  • What to do if multiple jobs would run at once (do we wait? stop the old one? run both?)
  • A way to pause the running of a CronJob, in case something’s wrong with it
  • Limits on old job history Remember, since we never read our own status, we need to have some other way tokeep track of whether a job has run. We can use at least one old job to dothis.

We’ll use several markers (// +comment) to specify additional metadata. Thesewill be used by controller-tools when generating our CRD manifest.As we’ll see in a bit, controller-tools will also use GoDoc to form descriptions forthe fields.

  3. // CronJobSpec defines the desired state of CronJob
  4. type CronJobSpec struct {
  5.     // +kubebuilder:validation:MinLength=0
  7.     // The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
  8.     Schedule string `json:"schedule"`
  10.     // +kubebuilder:validation:Minimum=0
  12.     // Optional deadline in seconds for starting the job if it misses scheduled
  13.     // time for any reason.  Missed jobs executions will be counted as failed ones.
  14.     // +optional
  15.     StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
  17.     // Specifies how to treat concurrent executions of a Job.
  18.     // Valid values are:
  19.     // - "Allow" (default): allows CronJobs to run concurrently;
  20.     // - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
  21.     // - "Replace": cancels currently running job and replaces it with a new one
  22.     // +optional
  23.     ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
  25.     // This flag tells the controller to suspend subsequent executions, it does
  26.     // not apply to already started executions.  Defaults to false.
  27.     // +optional
  28.     Suspend *bool `json:"suspend,omitempty"`
  30.     // Specifies the job that will be created when executing a CronJob.
  31.     JobTemplate batchv1beta1.JobTemplateSpec `json:"jobTemplate"`
  33.     // +kubebuilder:validation:Minimum=0
  35.     // The number of successful finished jobs to retain.
  36.     // This is a pointer to distinguish between explicit zero and not specified.
  37.     // +optional
  38.     SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
  40.     // +kubebuilder:validation:Minimum=0
  42.     // The number of failed finished jobs to retain.
  43.     // This is a pointer to distinguish between explicit zero and not specified.
  44.     // +optional
  45.     FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
  46. }

We define a custom type to hold our concurrency policy. It’s actuallyjust a string under the hood, but the type gives extra documentation,and allows us to attach validation on the type instead of the field,making the validation more easily reusable.

  3. // ConcurrencyPolicy describes how the job will be handled.
  4. // Only one of the following concurrent policies may be specified.
  5. // If none of the following policies is specified, the default one
  6. // is AllowConcurrent.
  7. // +kubebuilder:validation:Enum=Allow;Forbid;Replace
  8. type ConcurrencyPolicy string
  10. const (
  11.     // AllowConcurrent allows CronJobs to run concurrently.
  12.     AllowConcurrent ConcurrencyPolicy = "Allow"
  14.     // ForbidConcurrent forbids concurrent runs, skipping next run if previous
  15.     // hasn't finished yet.
  16.     ForbidConcurrent ConcurrencyPolicy = "Forbid"
  18.     // ReplaceConcurrent cancels currently running job and replaces it with a new one.
  19.     ReplaceConcurrent ConcurrencyPolicy = "Replace"
  20. )

Next, let’s design our status, which holds observed state. It contains any informationwe want users or other controllers to be able to easily obtain.

We’ll keep a list of actively running jobs, as well as the last time that we succesfullyran our job. Notice that we use metav1.Time instead of time.Time to get the stableserialization, as mentioned above.

  3. // CronJobStatus defines the observed state of CronJob
  4. type CronJobStatus struct {
  5.     // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
  6.     // Important: Run "make" to regenerate code after modifying this file
  8.     // A list of pointers to currently running jobs.
  9.     // +optional
  10.     Active []corev1.ObjectReference `json:"active,omitempty"`
  12.     // Information when was the last time the job was successfully scheduled.
  13.     // +optional
  14.     LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
  15. }

Finally, we have the rest of the boilerplate that we’ve already discussed.As previously noted, we don’t need to change this, except to mark thatwe want a status subresource, so that we behave like built-in kubernetes types.

  3. // +kubebuilder:object:root=true
  4. // +kubebuilder:subresource:status
  6. // CronJob is the Schema for the cronjobs API
  7. type CronJob struct {

Root Object Definitions

  2.     metav1.TypeMeta   `json:",inline"`
  3.     metav1.ObjectMeta `json:"metadata,omitempty"`
  5.     Spec   CronJobSpec   `json:"spec,omitempty"`
  6.     Status CronJobStatus `json:"status,omitempty"`
  7. }
  9. // +kubebuilder:object:root=true
  11. // CronJobList contains a list of CronJob
  12. type CronJobList struct {
  13.     metav1.TypeMeta `json:",inline"`
  14.     metav1.ListMeta `json:"metadata,omitempty"`
  15.     Items           []CronJob `json:"items"`
  16. }
  18. func init() {
  19.     SchemeBuilder.Register(&CronJob{}, &CronJobList{})
  20. }

Now that we have an API, we’ll need to write a controller to actuallyimplement the functionality.