CRD of pixiv.net

API Reference

This is a custom resource for efficiently generating multiple similar Job and CronJob manifests in the form of a common part and a set of differences.

To use k8s-job-wrapper with kustomize, add transform.yaml to the configurations section of your kustomization.yaml.

configurations:
  - https://pixiv.github.io/k8s-job-wrapper/kustomize/transform.yaml

Examples

Example of CronJob

There are PodProfile and CronJob:

apiVersion: pixiv.net/v1
kind: PodProfile
metadata:
  labels:
    app.kubernetes.io/name: k8s-job-wrapper
    app.kubernetes.io/managed-by: kustomize
  name: podprofile-sample
spec:
  template:
    spec:
      containers:
        - name: pi
          image: perl:5.34.0
          command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(500)"]
      restartPolicy: Never
---
apiVersion: pixiv.net/v1
kind: CronJob
metadata:
  labels:
    app.kubernetes.io/name: k8s-job-wrapper
    app.kubernetes.io/managed-by: kustomize
  name: cronjob-sample
spec:
  schedule: "* * * * *"
  jobProfile:
    podProfileRef: podprofile-sample
    patches:
      - op: replace
        path: /spec/containers/0/command
        value: ["perl", "-Mbignum=bpi", "-wle", "print bpi(10)"]
    jobParams:
      activeDeadlineSeconds: 120

These manifests will create the following resources:

apiVersion: batch/v1
kind: CronJob
metadata:
  creationTimestamp: "2025-04-21T07:58:23Z"
  generation: 1
  labels:
    app.kubernetes.io/created-by: pixiv-job-controller
    cronjobs.pixiv.net/name: cronjob-sample
  name: cronjob-sample-pxvcjob
  namespace: default
  ownerReferences:
  - apiVersion: pixiv.net/v1
    blockOwnerDeletion: true
    controller: true
    kind: CronJob
    name: cronjob-sample
    uid: 6b35de70-fcd0-4a6d-a35d-5f8cfe08a5de
  resourceVersion: "10603"
  uid: 364495ba-0239-4e7b-9911-f85059726f68
spec:
  concurrencyPolicy: Allow
  failedJobsHistoryLimit: 1
  jobTemplate:
    metadata:
      creationTimestamp: null
    spec:
      activeDeadlineSeconds: 120
      backoffLimit: 6
      completionMode: NonIndexed
      suspend: false
      template:
        metadata:
          creationTimestamp: null
        spec:
          containers:
          - command:
            - perl
            - -Mbignum=bpi
            - -wle
            - print bpi(10)
            image: perl:5.34.0
            imagePullPolicy: IfNotPresent
            name: pi
            resources: {}
            terminationMessagePath: /dev/termination-log
            terminationMessagePolicy: File
          dnsPolicy: ClusterFirst
          restartPolicy: Never
          schedulerName: default-scheduler
          securityContext: {}
          terminationGracePeriodSeconds: 30
  schedule: '* * * * *'
  successfulJobsHistoryLimit: 3
  suspend: false
status:
  lastScheduleTime: "2025-04-21T07:59:00Z"
  lastSuccessfulTime: "2025-04-21T07:59:02Z"

Example of Job

There are PodProfile and Job:

apiVersion: pixiv.net/v1
kind: PodProfile
metadata:
  labels:
    app.kubernetes.io/name: k8s-job-wrapper
    app.kubernetes.io/managed-by: kustomize
  name: podprofile-sample
spec:
  template:
    spec:
      containers:
        - name: pi
          image: perl:5.34.0
          command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(500)"]
      restartPolicy: Never
---
apiVersion: pixiv.net/v1
kind: Job
metadata:
  labels:
    app.kubernetes.io/name: k8s-job-wrapper
    app.kubernetes.io/managed-by: kustomize
  name: job-sample
spec:
  profile:
    podProfileRef: podprofile-sample
    patches:
      - op: replace
        path: /spec/containers/0/command
        value: ["perl", "-Mbignum=bpi", "-wle", "print bpi(100)"]
    jobParams:
      activeDeadlineSeconds: 120

These manifests will create the following resources:

apiVersion: batch/v1
kind: Job
metadata:
  creationTimestamp: "2025-04-21T07:58:23Z"
  generation: 1
  labels:
    app.kubernetes.io/created-by: pixiv-job-controller
    jobs.pixiv.net/job-spec-hash: 7dc5d648b9
    jobs.pixiv.net/name: job-sample
    pod-template-hash: 76bbc6b896
  name: job-sample-76bbc6b896
  namespace: default
  ownerReferences:
  - apiVersion: pixiv.net/v1
    blockOwnerDeletion: true
    controller: true
    kind: Job
    name: job-sample
    uid: 6d239c5f-8b88-47d2-8983-5d1b190d90e9
  resourceVersion: "10518"
  uid: 44d44c3f-78d2-416c-8638-3f375dce7aea
spec:
  activeDeadlineSeconds: 120
  backoffLimit: 6
  completionMode: NonIndexed
  completions: 1
  manualSelector: false
  parallelism: 1
  podReplacementPolicy: TerminatingOrFailed
  selector:
    matchLabels:
      batch.kubernetes.io/controller-uid: 44d44c3f-78d2-416c-8638-3f375dce7aea
  suspend: false
  template:
    metadata:
      creationTimestamp: null
      labels:
        batch.kubernetes.io/controller-uid: 44d44c3f-78d2-416c-8638-3f375dce7aea
        batch.kubernetes.io/job-name: job-sample-76bbc6b896
        controller-uid: 44d44c3f-78d2-416c-8638-3f375dce7aea
        job-name: job-sample-76bbc6b896
    spec:
      containers:
      - command:
        - perl
        - -Mbignum=bpi
        - -wle
        - print bpi(100)
        image: perl:5.34.0
        imagePullPolicy: IfNotPresent
        name: pi
        resources: {}
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Never
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
status:
  completionTime: "2025-04-21T07:58:26Z"
  conditions:
  - lastProbeTime: "2025-04-21T07:58:26Z"
    lastTransitionTime: "2025-04-21T07:58:26Z"
    message: Reached expected number of succeeded pods
    reason: CompletionsReached
    status: "True"
    type: SuccessCriteriaMet
  - lastProbeTime: "2025-04-21T07:58:26Z"
    lastTransitionTime: "2025-04-21T07:58:26Z"
    message: Reached expected number of succeeded pods
    reason: CompletionsReached
    status: "True"
    type: Complete
  ready: 0
  startTime: "2025-04-21T07:58:23Z"
  succeeded: 1
  terminating: 0
  uncountedTerminatedPods: {}

Packages

pixiv.net/v1

Package v1 contains API Schema definitions for the pixivnet v1 API group.

Resource Types

CronJob

CronJob represents a template of cronjobs.v1.batch.

CronJob generates cronjobs.v1.batch.spec from spec.jobProfile, and then combines it with spec.schedule, spec.timeZone, … to produce cronjobs.v1.batch.

The generated cronjobs.v1.batch will always have the following labels applied:

Where $NAME_OF_CRONJOB is the metadata.name.

The generated cronjobs.v1.batch will have the suffix -pxvcjob appended to its name. The maximum length of metadata.name of cronjobs.v1.batch is 52 characters. Therefore, the maximum length of metadata.name of CronJob is 44 characters.

Appears in: - CronJobList

Field Description Default Validation
apiVersion string pixiv.net/v1
kind string CronJob
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec CronJobSpec
status CronJobStatus

CronJobList

CronJobList contains a list of CronJob.

Field Description Default Validation
apiVersion string pixiv.net/v1
kind string CronJobList
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items CronJob array

CronJobMetadata

Appears in: - CronJobSpec

Field Description Default Validation
labels object (keys:string, values:string) Additional labels for generated cronjobs.v1.batch.
annotations object (keys:string, values:string) Additional annotations for generated cronjobs.v1.batch.

CronJobSpec

CronJobSpec defines the desired state of CronJob.

Appears in: - CronJob

Field Description Default Validation
jobProfile JobProfileSpec
cronJobMetadata CronJobMetadata Additional cronjobs.v1.batch.metadata.
schedule string The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
timeZone string The time zone name for the given schedule, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
If not specified, this will default to the time zone of the kube-controller-manager process.
The set of valid time zone names and the time zone offset is loaded from the system-wide time zone
database by the API server during CronJob validation and the controller manager during execution.
If no system-wide time zone database can be found a bundled version of the database is used instead.
If the time zone name becomes invalid during the lifetime of a CronJob or due to a change in host
configuration, the controller will stop creating new new Jobs and will create a system event with the
reason UnknownTimeZone.
More information can be found in https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#time-zones
startingDeadlineSeconds integer Optional deadline in seconds for starting the job if it misses scheduled
time for any reason. Missed jobs executions will be counted as failed ones.
concurrencyPolicy ConcurrencyPolicy Specifies how to treat concurrent executions of a Job.
Valid values are:
- “Allow” (default): allows CronJobs to run concurrently;
- “Forbid”: forbids concurrent runs, skipping next run if previous run hasn’t finished yet;
- “Replace”: cancels currently running job and replaces it with a new one		 Allow
suspend boolean This flag tells the controller to suspend subsequent executions, it does
not apply to already started executions. Defaults to false.		 false
successfulJobsHistoryLimit integer The number of successful finished jobs to retain.
This is a pointer to distinguish between explicit zero and not specified.		 3
failedJobsHistoryLimit integer The number of failed finished jobs to retain.
This is a pointer to distinguish between explicit zero and not specified.		 1

CronJobStatus

CronJobStatus defines the observed state of CronJob.

Appears in: - CronJob

Field Description Default Validation
conditions Condition array Conditions represent the latest available observations of an object’s state.
collisionCount integer Count of hash collisions for the Job. The Job controller uses this
field as a collision avoidance mechanism when it needs to create the name for the
newest jobs.v1.batch.

Job

Job represents a template of jobs.v1.batch.

The Job creates a jobs.v1.batch manifest from the PodProfile specified in spec.profile.podProfileRef and spec.profile.jobParams, and applies spec.profile.patches. The generated jobs.v1.batch will always have the following labels:

$NAME_OF_JOB is the value of metadata.name. $HASH_OF_JOB_SPEC is the hash value of jobs.v1.batch.spec.

The Job generates a jobs.v1.batch in the following cases:

The name of the jobs.v1.batch to be generated will have an 11-character suffix appended to metadata.name. Therefore, metadata.name can be a maximum of 52 characters long.

Appears in: - JobList

Field Description Default Validation
apiVersion string pixiv.net/v1
kind string Job
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec JobSpec
status JobStatus

JobList

JobList contains a list of Job.

Field Description Default Validation
apiVersion string pixiv.net/v1
kind string JobList
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items Job array

JobMetadata

Appears in: - JobProfileSpec

Field Description Default Validation
labels object (keys:string, values:string) Additional labels for generated jobs.v1.batch.
annotations object (keys:string, values:string) Additional annotations for generated jobs.v1.batch.

JobParams

jobs.v1.batch.spec without template, ttlSecondsAfterFinished.

Appears in: - JobProfileSpec

Field Description Default Validation
parallelism integer Specifies the maximum desired number of pods the job should
run at any given time. The actual number of pods running in steady state will
be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism),
i.e. when the work left to do is less than max parallelism.
More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
completions integer Specifies the desired number of successfully finished pods the
job should be run with. Setting to null means that the success of any
pod signals the success of all pods, and allows parallelism to have any positive
value. Setting to 1 means that parallelism is limited to 1 and the success of that
pod signals the success of the job.
More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
activeDeadlineSeconds integer Specifies the duration in seconds relative to the startTime that the job
may be continuously active before the system tries to terminate it; value
must be positive integer. If a Job is suspended (at creation or through an
update), this timer will effectively be stopped and reset when the Job is
resumed again.
podFailurePolicy PodFailurePolicy Specifies the policy of handling failed pods. In particular, it allows to
specify the set of actions and conditions which need to be
satisfied to take the associated action.
If empty, the default behaviour applies - the counter of failed pods,
represented by the jobs’s .status.failed field, is incremented and it is
checked against the backoffLimit. This field cannot be used in combination
with restartPolicy=OnFailure.
successPolicy SuccessPolicy successPolicy specifies the policy when the Job can be declared as succeeded.
If empty, the default behavior applies - the Job is declared as succeeded
only when the number of succeeded pods equals to the completions.
When the field is specified, it must be immutable and works only for the Indexed Jobs.
Once the Job meets the SuccessPolicy, the lingering pods are terminated.
This field is beta-level. To use this field, you must enable the
JobSuccessPolicy feature gate (enabled by default).
backoffLimit integer Specifies the number of retries before marking this job failed.
Defaults to 6		 6
backoffLimitPerIndex integer Specifies the limit for the number of retries within an
index before marking this index as failed. When enabled the number of
failures per index is kept in the pod’s
batch.kubernetes.io/job-index-failure-count annotation. It can only
be set when Job’s completionMode=Indexed, and the Pod’s restart
policy is Never. The field is immutable.
This field is beta-level. It can be used when the JobBackoffLimitPerIndex
feature gate is enabled (enabled by default).
maxFailedIndexes integer Specifies the maximal number of failed indexes before marking the Job as
failed, when backoffLimitPerIndex is set. Once the number of failed
indexes exceeds this number the entire Job is marked as Failed and its
execution is terminated. When left as null the job continues execution of
all of its indexes and is marked with the Complete Job condition.
It can only be specified when backoffLimitPerIndex is set.
It can be null or up to completions. It is required and must be
less than or equal to 10^4 when is completions greater than 10^5.
This field is beta-level. It can be used when the JobBackoffLimitPerIndex
feature gate is enabled (enabled by default).
selector LabelSelector A label query over pods that should match the pod count.
Normally, the system sets this field for you.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
manualSelector boolean manualSelector controls generation of pod labels and pod selectors.
Leave manualSelector unset unless you are certain what you are doing.
When false or unset, the system pick labels unique to this job
and appends those labels to the pod template. When true,
the user is responsible for picking unique labels and specifying
the selector. Failure to pick a unique label may cause this
and other jobs to not function correctly. However, You may see
manualSelector=true in jobs that were created with the old extensions/v1beta1
API.
More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#specifying-your-own-pod-selector
ttlSecondsAfterFinished integer ttlSecondsAfterFinished limits the lifetime of a Job that has finished
execution (either Complete or Failed). If this field is set,
ttlSecondsAfterFinished after the Job finishes, it is eligible to be
automatically deleted. When the Job is being deleted, its lifecycle
guarantees (e.g. finalizers) will be honored. If this field is unset,
the Job won’t be automatically deleted. If this field is set to zero,
the Job becomes eligible to be deleted immediately after it finishes.
When CRD Job uses this, even if the TTL is expired, one Job will remain. It will be reflected in
the jobs.pixiv.net/ttl-seconds-after-finished annotation instead of jobs.v1.batch.spec.ttlSecondsAfterFinished.
completionMode CompletionMode completionMode specifies how Pod completions are tracked. It can be
NonIndexed (default) or Indexed.
NonIndexed means that the Job is considered complete when there have
been .spec.completions successfully completed Pods. Each Pod completion is
homologous to each other.
Indexed means that the Pods of a
Job get an associated completion index from 0 to (.spec.completions - 1),
available in the annotation batch.kubernetes.io/job-completion-index.
The Job is considered complete when there is one successfully completed Pod
for each index.
When value is Indexed, .spec.completions must be specified and
.spec.parallelism must be less than or equal to 10^5.
In addition, The Pod name takes the form
$(job-name)-$(index)-$(random-string),
the Pod hostname takes the form $(job-name)-$(index).
More completion modes can be added in the future.
If the Job controller observes a mode that it doesn’t recognize, which
is possible during upgrades due to version skew, the controller
skips updates for the Job.		 NonIndexed
suspend boolean suspend specifies whether the Job controller should create Pods or not. If
a Job is created with suspend set to true, no Pods are created by the Job
controller. If a Job is suspended after creation (i.e. the flag goes from
false to true), the Job controller will delete all active Pods associated
with this Job. Users must design their workload to gracefully handle this.
Suspending a Job will reset the StartTime field of the Job, effectively
resetting the ActiveDeadlineSeconds timer too. Defaults to false.		 false
podReplacementPolicy PodReplacementPolicy podReplacementPolicy specifies when to create replacement Pods.
Possible values are:
- TerminatingOrFailed means that we recreate pods
when they are terminating (has a metadata.deletionTimestamp) or failed.
- Failed means to wait until a previously created Pod is fully terminated (has phase
Failed or Succeeded) before creating a replacement Pod.
When using podFailurePolicy, Failed is the the only allowed value.
TerminatingOrFailed and Failed are allowed values when podFailurePolicy is not in use.
This is an beta field. To use this, enable the JobPodReplacementPolicy feature toggle.
This is on by default.
managedBy string ManagedBy field indicates the controller that manages a Job. The k8s Job
controller reconciles jobs which don’t have this field at all or the field
value is the reserved string kubernetes.io/job-controller, but skips
reconciling Jobs with a custom value for this field.
The value must be a valid domain-prefixed path (e.g. acme.io/foo) -
all characters before the first “/” must be a valid subdomain as defined
by RFC 1123. All characters trailing the first “/” must be valid HTTP Path
characters as defined by RFC 3986. The value cannot exceed 63 characters.
This field is immutable.
This field is alpha-level. The job controller accepts setting the field
when the feature gate JobManagedBy is enabled (disabled by default).

JobPatch

JobPatch defines the patch to be applied to template of PodProfile. For examples, rename container: 
op: replace
path: /spec/containers/0/name
value: simple
Replace command: 
op: replace
path: /spec/containers/0/command
value: ["perl", "-Mbignum=bpi", "-wle", "print bpi(100)"]

Appears in: - JobProfileSpec

Field Description Default Validation
op string Operation to perform.
path string JSON-pointer that references a location within the template where the operation is performed.
The root of path will be jobs.v1.batch.spec.template.
value JSON Any yaml object.
from string

JobProfileSpec

Appears in: - CronJobSpec - JobSpec

Field Description Default Validation
podProfileRef string Name of PodProfile that this refers to.
patches JobPatch array Patches to be applied to template of PodProfile.
jobParams JobParams jobs.v1.batch.spec configuration options.
jobMetadata JobMetadata Additional jobs.v1.batch.metadata.

JobSpec

JobSpec defines the desired state of Job.

Appears in: - Job

Field Description Default Validation
profile JobProfileSpec
jobsHistoryLimit integer JobsHistoryLimit is the number of jobs to retain.
Value must be non-negative integer.
Default is 3.		 3

JobStatus

JobStatus defines the observed state of Job.

Appears in: - Job

Field Description Default Validation
conditions Condition array Conditions represent the latest available observations of an object’s state.
collisionCount integer Count of hash collisions for the Job. The Job controller uses this
field as a collision avoidance mechanism when it needs to create the name for the
newest jobs.v1.batch.

PodProfile

PodProfile represents the configuration of a Pod.

Appears in: - PodProfileList

Field Description Default Validation
apiVersion string pixiv.net/v1
kind string PodProfile
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec PodProfileSpec
status PodProfileStatus

PodProfileList

PodProfileList contains a list of PodProfile.

Field Description Default Validation
apiVersion string pixiv.net/v1
kind string PodProfileList
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.
items PodProfile array

PodProfileSpec

PodProfileSpec defines the desired state of PodProfile.

Appears in: - PodProfile

Field Description Default Validation
template PodTemplateSpec Template describes the pods that will be created.

PodProfileStatus

PodProfileStatus defines the observed state of PodProfile.

Appears in: - PodProfile