Docs / Reference / Workers and storage

WorkerScript

WorkerScript represents a Cloudflare Worker script and its bindings.

API version: kflare.dev/v1alpha1
Scope: Namespaced
Short name: cfworker
Token permission: Account · Workers Scripts · Edit

Example

Every field, with the sample's values. The live lines are the repository's sample, which applies as it is; the commented ones are the other fields, filled from other samples where one sets them. Some exclude each other, so check the rules before you uncomment several.

workerscript.yaml

apiVersion: kflare.dev/v1alpha1
kind: WorkerScript
metadata:
  name: example-worker
  namespace: default
spec:
  name: example-worker
  accountRef:
    name: my-account
  format: module
  compatibilityDate: "2024-09-23"
  script: |
    export default {
      async fetch(request, env) {
        return new Response(`${env.GREETING} from kflare`);
      },
    };
  bindings:
    - name: GREETING
      plainText: Hello
    - name: API_KEY
      secretKeyRef:
        name: example-worker-secrets
        key: api-key
    # - name: GREETING
    #   plainText: Hello
    #   secretKeyRef:
    #     name: example-worker-secrets
    #     key: api-key
    #   kvNamespaceID: <kvNamespaceID>
    #   kvNamespaceRef:
    #     name: <name>
    #   r2BucketName: <r2BucketName>
    #   r2BucketRef:
    #     name: <name>
  # compatibilityFlags:
  #   - <compatibilityFlags>
  # scriptConfigMapRef:
  #   key: <key>
  #   name: <name>

Spec

What you set, with the limits the API server enforces.

Field	Description
`accountRef` objectrequiredimmutable	AccountRef references the CloudflareAccount that owns the Worker. Immutable after creation.
`accountRef.name` string	Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: `""`
`bindings` []object	Bindings expose values and resources to the Worker as environment bindings. Names must be unique. Limits: at most 64 items Rule: exactly one of plainText, secretKeyRef, kvNamespaceRef, kvNamespaceID, r2BucketRef or r2BucketName must be set
`bindings[].kvNamespaceID` string	KVNamespaceID binds a Workers KV namespace by ID. Prefer kvNamespaceRef for namespaces managed by kflare. Limits: at least 1 character
`bindings[].kvNamespaceRef` object	KVNamespaceRef binds the Workers KV namespace of a KVNamespace in the same namespace. The Worker is uploaded once the KVNamespace is ready, and the KVNamespace is not deleted while this binding exists.
`bindings[].kvNamespaceRef.name` string	Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: `""`
`bindings[].name` stringrequired	Name of the binding, as seen by the Worker (env.NAME). Limits: matches `^[A-Za-z_][A-Za-z0-9_]*$`
`bindings[].plainText` string	PlainText binds a plain text value. Limits: at least 1 character
`bindings[].r2BucketName` string	R2BucketName binds an R2 bucket by name. Prefer r2BucketRef for buckets managed by kflare. Limits: at least 1 character
`bindings[].r2BucketRef` object	R2BucketRef binds the R2 bucket of an R2Bucket in the same namespace. The Worker is uploaded once the R2Bucket is ready, and the R2Bucket is not deleted while this binding exists.
`bindings[].r2BucketRef.name` string	Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: `""`
`bindings[].secretKeyRef` object	SecretKeyRef binds a secret text value read from a key of a Secret in the same namespace. The value is sent to Cloudflare and never written to this resource's status.
`bindings[].secretKeyRef.key` stringrequired	Key within the ConfigMap or Secret. Limits: at least 1 character
`bindings[].secretKeyRef.name` stringrequired	Name of the ConfigMap or Secret. Limits: at least 1 character
`compatibilityDate` string	CompatibilityDate pins the Workers runtime behaviour (YYYY-MM-DD). Limits: matches `^\d{4}-\d{2}-\d{2}$`
`compatibilityFlags` []string	CompatibilityFlags enable or disable individual runtime features. Limits: at most 64 items
`format` string	Format is the script syntax: "module" (ES modules) or "serviceWorker". Default: `module` One of: `module`, `serviceWorker`
`name` stringrequiredimmutable	Name is the Worker's script name in Cloudflare. Immutable after creation. Limits: matches `^[a-z0-9]([a-z0-9_-]{0,61}[a-z0-9])?$`
`script` string	Script is the Worker source code. Set either this or ScriptConfigMapRef. Limits: at least 1 character
`scriptConfigMapRef` object	ScriptConfigMapRef reads the Worker source code from a key of a ConfigMap in the same namespace. Set either this or Script.
`scriptConfigMapRef.key` stringrequired	Key within the ConfigMap or Secret. Limits: at least 1 character
`scriptConfigMapRef.name` stringrequired	Name of the ConfigMap or Secret. Limits: at least 1 character

Rules

Checked across fields when the resource is applied.

exactly one of script or scriptConfigMapRef must be set

Status

What kflare reports. conditions holds the Ready condition, whose reason says why a resource isn't ready.

Field	Description
`appliedHash` string	AppliedHash identifies the desired state last uploaded: the script, format, compatibility settings and bindings. Secret bindings contribute the Secret's UID and resourceVersion, never its value.
`cloudflareMetadata` object	CloudflareMetadata holds identifiers returned by the Cloudflare API.
`cloudflareMetadata.etag` string	Etag is Cloudflare's hash of the uploaded code. It does not change when only bindings or compatibility settings change.
`cloudflareMetadata.modifiedOn` string	ModifiedOn is the modification time Cloudflare reported for kflare's last upload, kept at full precision. A different value on Cloudflare means the Worker was changed outside kflare.
`cloudflareMetadata.scriptName` string	ScriptName is the name of the Worker kflare last uploaded.
`conditions` []object	Conditions represent the latest available observations of the Worker state.

kubectl get

The columns kubectl get workerscripts prints.

Column	Source
SCRIPT	.spec.name
MODIFIED	.status.cloudflareMetadata.modifiedOn
READY	.status.conditions[?(@.type=="Ready")].status
AGE	.metadata.creationTimestamp

Samples

From the repository's config/samples, comments included.

cloudflare_v1alpha1_workerscript.yaml

apiVersion: kflare.dev/v1alpha1
kind: WorkerScript
metadata:
  name: example-worker
  namespace: default
spec:
  name: example-worker            # script name in Cloudflare (immutable)
  accountRef:
    name: my-account
  format: module
  compatibilityDate: "2024-09-23"
  # Inline code; use scriptConfigMapRef: {name, key} to read it from a ConfigMap instead.
  script: |
    export default {
      async fetch(request, env) {
        return new Response(`${env.GREETING} from kflare`);
      },
    };
  bindings:
    - name: GREETING
      plainText: Hello
    - name: API_KEY               # read from Secret example-worker-secrets, key api-key
      secretKeyRef:
        name: example-worker-secrets
        key: api-key
# A KVNamespace or R2Bucket in the same namespace is bound by reference, such as
# the KVNamespace sample:
#
#   bindings:
#     - name: CACHE
#       kvNamespaceRef:
#         name: example-kvnamespace

On GitHub