Edit on GitHub

Tiltfile API Reference

class api.Blob

The result of executing a command on your local system.

Under the hood, a Blob is just a string, but we wrap it this way so Tilt knows the difference between a string meant to convey content and a string indicating, say, a filepath.

To wrap a string as a blob, call blob(my_str)

class api.CustomBuild

An image that was created with custom_build

add_fast_build()

Returns a FastBuild that is associated with the image that was built from a custom_build. When the container needs to be rebuilt it will be built using the CustomBuild. Otherwise update will be done with the FastBuild instructions.

Return type:FastBuild
class api.FastBuild

An image that was created with fast_build

add(src, dest)

Adds the content from src into the image at path dest.

Parameters:
  • src (str) – The path to content to be added to the image (absolute, or relative to the location of the Tiltfile).
  • dest (str) – The path in the image where the content should be added.
Return type:

FastBuild

hot_reload()

Setting this on a FastBuild image tells Tilt that this container knows how to automatically reload any changes in the container. As a result there is no need to restart it.

This is useful for containers that run something like nodemon or webpack Hot Module Replacement to update running processes quickly.

Return type:None
run(cmd, trigger=[])

Runs cmd as a build step in the image.

Parameters:
  • cmd (str) – A shell command.
  • trigger (Union[List[str], str]) – If the trigger argument is specified, the build step is only run on changes to the given file(s).
Return type:

None

class api.K8sObjectID
name

The object’s name (e.g., “my-service”)

Type:str
kind

The object’s kind (e.g., “deployment”)

Type:str
namespace

The object’s namespace (e.g., “default”)

Type:str
group

The object’s group (e.g., “apps”)

Type:str
class api.LiveUpdateStep

A step in the process of performing a LiveUpdate on an image’s container.

For details, see the Live Update documentation.

api.blob(contents)

Creates a Blob object that wraps the provided string. Useful for passing strings in to functions that expect a Blob, e.g. k8s_yaml.

Return type:Blob
api.container_restart()

Specify that a container should be restarted when it is live-updated.

May only be included in a live_update once, and only as the last step.

Return type:LiveUpdateStep
api.custom_build(ref, command, deps, tag='', disable_push=False, live_update=[])

Provide a custom command that will build an image.

Returns an object which can be used to create a FastBuild.

The command must publish an image with the name & tag $EXPECTED_REF.

Tilt will raise an error if the command exits successfully, but the registry does not contain an image with the ref $EXPECTED_REF.

Example

custom_build(
  'gcr.io/foo',
  'docker build -t $EXPECTED_REF .',
  ['.'],
)
Parameters:
  • ref (str) – name for this image (e.g. ‘myproj/backend’ or ‘myregistry/myproj/backend’). If this image will be used in a k8s resource(s), this ref must match the spec.container.image param for that resource(s).
  • command (str) – a command that, when run in the shell, builds an image puts it in the registry as ref. Must produce an image named $EXPECTED_REF
  • deps (List[str]) – a list of files or directories to be added as dependencies to this image. Tilt will watch those files and will rebuild the image when they change.
  • tag (str) – Some tools can’t change the image tag at runtime. They need a pre-specified tag. Tilt will set $EXPECTED_REF = image_name:tag, then re-tag it with its own tag before pushing to your cluster. See the bazel guide for an example.
  • disable_push (bool) – whether Tilt should push the image in to the registry that the Kubernetes cluster has access to. Set this to true if your command handles pushing as well.
  • live_update (List[LiveUpdateStep]) –

    set of steps for updating a running container (see Live Update documentation).

Return type:

CustomBuild

api.decode_json(json)

Deserializes a given string from JSON to Starlark. Fails if the string can’t be parsed as JSON.

Return type:Union[Dict[str, Any], List[Any]]
api.default_registry(registry)

Specifies that any images that Tilt builds should be renamed so that they have the specified Docker registry.

This is useful if, e.g., a repo is configured to push to Google Container Registry, but you want to use Elastic Container Registry instead, without having to edit a bunch of configs. For example, default_registry("gcr.io/myrepo") would cause docker.io/alpine to be rewritten to gcr.io/myrepo/docker.io_alpine

Parameters:registry (str) – The registry that all built images should be renamed to use.

Images are renamed following these rules:

  1. Replace / and @ with _.
  2. Prepend the value of registry and a /.

e.g., with default_registry('gcr.io/myorg'), user-service becomes gcr.io/myorg/user-service.

(Note: this logic is currently crude, on the assumption that development image names are ephemeral and unimportant. Please let us know if they don’t suit you!)

Cf. our using a personal registry guide

Return type:None
api.docker_build(ref, context, build_args={}, dockerfile='Dockerfile', dockerfile_contents='', live_update=[])

Builds a docker image.

Note that you can’t set both the dockerfile and dockerfile_contents arguments (will throw an error).

Example: docker_build('myregistry/myproj/backend', '/path/to/code') is roughly equivalent to the call docker build /path/to/code -t myregistry/myproj/backend

Parameters:
  • ref (str) – name for this image (e.g. ‘myproj/backend’ or ‘myregistry/myproj/backend’). If this image will be used in a k8s resource(s), this ref must match the spec.container.image param for that resource(s).
  • context (str) – path to use as the Docker build context.
  • build_args (Dict[str, str]) – build-time variables that are accessed like regular environment variables in the RUN instruction of the Dockerfile. See the Docker Build Arg documentation
  • dockerfile (str) – path to the Dockerfile to build
  • dockerfile_contents (Union[str, Blob]) – raw contents of the Dockerfile to use for this build
  • live_update (List[LiveUpdateStep]) –

    set of steps for updating a running container (see Live Update documentation).

Return type:

None

api.fail(msg)

Raises an error that cannot be intercepted. Can be used anywhere in a Tiltfile.

Return type:None
api.fall_back_on(files)

Specify that any changes to the given files will cause Tilt to fall back to a full image build (rather than performing a live update).

fall_back_on step(s) may only go at the beginning of your list of steps.

(Files must be a subset of the files that we’re already watching for this image; that is, if any files fall outside of DockerBuild.context or CustomBuild.deps, an error will be raised.)

Parameters:files (Union[str, List[str]]) – a string or list of strings of files. If relative, will be evaluated relative to the Tiltfile. Tilt compares these to the local paths of edited files when determining whether to fall back to a full image build.
Return type:LiveUpdateStep
api.fast_build(img_name, dockerfile_path, entrypoint='')

Initiates a docker image build that supports add s and run s, and that uses a cache for subsequent builds.

See the fast build documentation.

Return type:FastBuild
api.filter_yaml(yaml, labels=None, name=None, namespace=None, kind=None, api_version=None)

Call this with a path to a file that contains YAML, or with a Blob of YAML. (E.g. it can be called on the output of kustomize or helm.)

Captures the YAML entities that meet the filter criteria and returns them as a blob; returns the non-matching YAML as the second return value.

For example, if you have a file of all your YAML, but only want to pass a few elements to Tilt:

# extract all YAMLs matching labels "app=foobar"
foobar_yaml, rest = filter_yaml('all.yaml', labels={'app': 'foobar'}
k8s_yaml(foobar_yaml)

# extract YAMLs of kind "deployment" with metadata.name "baz"
baz_yaml, rest = filter_yaml(rest, name='baz', kind='deployment')
k8s_yaml(baz_yaml)
Parameters:
  • yaml (Union[str, List[str], Blob]) – Path(s) to YAML, or YAML as a Blob.
  • labels (Optional[dict]) – return only entities matching these labels. (Matching entities must satisfy all of the specified label constraints, though they may have additional labels as well: see the Kubernetes docs for more info.)
  • name (Optional[str]) – Case-insensitive regexp specifying the metadata.name property of entities to match
  • namespace (Optional[str]) – Case-insensitive regexp specifying the metadata.namespace property of entities to match
  • kind (Optional[str]) – Case-insensitive regexp specifying the kind of entities to match (e.g. “Service”, “Deployment”, etc.).
  • api_version (Optional[str]) – Case-insensitive regexp specifying the apiVersion for kind, (e.g., “apps/v1”)
Returns:

2-element tuple containing

  • matching (Blob): blob of YAML entities matching given filters
  • rest (Blob): the rest of the YAML entities

api.helm(pathToChartDir)

Run helm template on a given directory that contains a chart and return the fully rendered YAML as a Blob Chart directory is watched (See watch_file).

Parameters:pathToChartDir (str) – Path to the directory locally (absolute, or relative to the location of the Tiltfile).
Return type:Blob
api.k8s_kind(kind, api_version=None, *, image_json_path)

Tells Tilt about a k8s kind. Primarily intended for defining where your CRD specifies image names.

(Note the * in the signature means image_json_path must be passed as a keyword, e.g., image_json_path=”{.spec.image}”)

Example

# Fission has a CRD named "Environment"
k8s_yaml('deploy/fission.yaml')
k8s_kind('Environment', image_json_path='{.spec.runtime.image}')
Parameters:
  • kind (str) – Case-insensitive regexp specifying he value of the kind field in the k8s object definition (e.g., “Deployment”)
  • api_version (Optional[str]) – Case-insensitive regexp specifying the apiVersion for kind, (e.g., “apps/v1”)
  • image_json_path (Union[str, List[str]]) – Either a string or a list of string containing json path(s) within that kind’s definition specifying images deployed with k8s objects of that type. This uses the k8s json path template syntax, described here.
api.k8s_resource(workload, new_name='', port_forwards=[], extra_pod_selectors=[])

Configures a kubernetes resources

This description apply to k8s_resource_assembly_version 2. If you are running Tilt version < 0.8.0 and/or do not call k8s_resource_assembly_version(2), see k8s_resource_v1_DEPRECATED() instead.

Parameters:
  • workload (str) – which workload’s resource to configure. This is a colon-separated string consisting of one or more of (name, kind, namespace, group), e.g., “redis”, “redis:deployment”, or “redis:deployment:default”. k8s_resource searches all loaded k8s workload objects for an object matching all given fields. If there’s exactly one, k8s_resource configures options for that workload. If there’s not exactly one, k8s_resource raises an error. (e.g., “redis” suffices if there’s only one object named “redis”, but if there’s both a deployment and a cronjob named “redis”, you’d need to specify “redis:deployment”).
  • new_name (str) – if non-empty, will be used as the new name for this resource
  • port_forwards (Union[str, int, List[int]]) – Local ports to connect to the pod. If no target port is specified, will use the first container port. Example values: 9000 (connect localhost:9000 to the default container port), ‘9000:8000’ (connect localhost:9000 to the container port 8000), [‘9000:8000’, ‘9001:8001’] (connect localhost:9000 and :9001 to the container ports 8000 and 8001, respectively).
  • extra_pod_selectors (Union[Dict[str, str], List[Dict[str, str]]]) – In addition to relying on Tilt’s heuristics to automatically find K8S resources associated with this resource, a user may specify extra labelsets to force entities to be associated with this resource. An entity will be associated with this resource if it has all of the labels in at least one of the entries specified (but still also if it meets any of Tilt’s usual mechanisms).
Return type:

None

api.k8s_resource_assembly_version(version)

Specifies which version of k8s resource assembly loading to use.

This function is deprecated and will be removed. See Resource Assembly Migration for information.

Changes the behavior of k8s_resource().

Return type:None
api.k8s_resource_v1_DEPRECATED(name, yaml='', image='', port_forwards=[], extra_pod_selectors=[])

NOTE: This is actually named k8s_resource(). This documents the behavior of this method after a call to k8s_resource_assembly_version() with value 1. This behavior is deprecated and will be removed. See Resource Assembly Migration for information.

Creates a kubernetes resource that tilt can deploy using the specified image.

Parameters:
  • name (str) – What call this resource in the UI. If image is not specified name will be used as the image to group by.
  • yaml (Union[str, Blob]) – Optional YAML. If this arg is not passed, we expect to be able to extract it from an existing resource (by looking for a k8s container running the specified image).
  • image (Union[str, FastBuild]) – An optional Image. If the image is not passed, we expect to be able to extract it from an existing resource.
  • port_forwards (Union[str, int, List[int]]) – Local ports to connect to the pod. If no target port is specified, will use the first container port. Example values: 9000 (connect localhost:9000 to the default container port), ‘9000:8000’ (connect localhost:9000 to the container port 8000), [‘9000:8000’, ‘9001:8001’] (connect localhost:9000 and :9001 to the container ports 8000 and 8001, respectively).
  • extra_pod_selectors (Union[Dict[str, str], List[Dict[str, str]]]) – In addition to relying on Tilt’s heuristics to automatically find K8S resources associated with this resource, a user may specify extra labelsets to force entities to be associated with this resource. An entity will be associated with this resource if it has all of the labels in at least one of the entries specified (but still also if it meets any of Tilt’s usual mechanisms).
Return type:

None

api.k8s_yaml(yaml)

Call this with a path to a file that contains YAML, or with a Blob of YAML.

We will infer what (if any) of the k8s resources defined in your YAML correspond to Images defined elsewhere in your Tiltfile (matching based on the DockerImage ref and on pod selectors). Any remaining YAML is YAML that Tilt applies to your k8s cluster independently.

Any YAML files are watched (See watch_file).

Examples:

# path to file
k8s_yaml('foo.yaml')

# list of paths
k8s_yaml(['foo.yaml', 'bar.yaml'])

# Blob, i.e. `local` output (in this case, script output)
templated_yaml = local('./template_yaml.sh')
k8s_yaml(templated_yaml)
Parameters:yaml (Union[str, List[str], Blob]) – Path(s) to YAML, or YAML as a Blob.
Return type:None
api.kustomize(pathToDir)

Run kustomize on a given directory and return the resulting YAML as a Blob Directory is watched (See watch_file).

Parameters:pathToDir (str) – Path to the directory locally (absolute, or relative to the location of the Tiltfile).
Return type:Blob
api.listdir(directory, recursive=False)

Returns all the files at the top level of the provided directory. If recursive is set to True, returns all files that are inside of the provided directory, recursively.

Directory is watched (See watch_file).

Return type:List[str]
api.local(cmd)

Runs cmd, waits for it to finish, and returns its stdout as a Blob.

Return type:Blob
api.read_file(file_path, default=None)

Reads file and returns its contents.

If the file_path does not exist and default is not None, default will be returned. In any other case, an error reading file_path will be a Tiltfile load error.

Parameters:
  • file_path (str) – Path to the file locally (absolute, or relative to the location of the Tiltfile).
  • default (Optional[str]) – If not None and the file at file_path does not exist, this value will be returned.
Return type:

Blob

api.read_json(path, default=None)

Reads the file at path and deserializes its contents as JSON

If the path does not exist and default is not None, default will be returned. In any other case, an error reading path will be a Tiltfile load error.

Parameters:
  • path (str) – Path to the file locally (absolute, or relative to the location of the Tiltfile).
  • default (Optional[str]) – If not None and the file at path does not exist, this value will be returned.
Return type:

Union[Dict[str, Any], List[Any]]

api.read_yaml(path, default=None)

Reads the file at path and deserializes its contents as YAML

If the path does not exist and default is not None, default will be returned. In any other case, an error reading path will be a Tiltfile load error.

Parameters:
  • path (str) – Path to the file locally (absolute, or relative to the location of the Tiltfile).
  • default (Optional[str]) – If not None and the file at path does not exist, this value will be returned.
Return type:

Union[Dict[str, Any], List[Any]]

api.run(cmd, trigger=[])

Specify that the given cmd should be executed when updating an image’s container

May not precede any sync steps in a live_update.

Parameters:
  • cmd (str) – A shell command.
  • trigger (Union[List[str], str]) – If the trigger argument is specified, the build step is only run when there are changes to the given file(s). Paths relative to Tiltfile.
Return type:

LiveUpdateStep

api.sync(local_path, remote_path)

Specify that any changes to localPath should be synced to remotePath

May not follow any run steps in a live_update.

Parameters:
  • localPath – A path relative to the Tiltfile’s directory. Changes to files matching this path will be synced to remotePath. Can be a file (in which case just that file will be synced) or directory (in which case any files recursively under that directory will be synced).
  • remotePath – container path to which changes will be synced. Must be absolute.
Return type:

LiveUpdateStep

api.watch_file(file_path)

Watches a file. If the file is changed a re-exectution of the Tiltfile is triggered.

Parameters:file_path (str) – Path to the file locally (absolute, or relative to the location of the Tiltfile).
Return type:None
api.workload_to_resource_function(fn)

(Only supported with k8s_resource_assembly_version() >= 2(2)) Provide a function that will be used to name Tilt resources.

Tilt will auto-generate resource names for you. If you do not like the names it generates, you can use this to customize how Tilt generates names.

Example

# name all tilt resources after the k8s object namespace + name
def resource_name(id):
  return id.namespace + '-' + id.name
workload_to_resource_function(resource_name)

The names it generates must be unique (i.e., two workloads can’t map to the same resource name).

Parameters:fn (Callable[[K8sObjectID], str]) – A function that takes a K8sObjectID and returns a str. Tilt will call this function once for each workload to determine that workload’s resource’s name.
Return type:None