Skaffold – Environment Management

Docs: Load environment variables from a file

Mon, 01 Jan 0001 00:00:00 +0000

In Skaffold, a skaffold.env file can be defined in the project root directory to specify environment variables that Skaffold will load into the process. This provides a more organized and manageable way of setting environment variables, rather than passing them as command line arguments.

The skaffold.env file should be in the format of KEY=value pairs, with one pair per line. Skaffold will automatically load these variables into the environment before running any commands.

Here is an example skaffold.env file:

ENV_VAR_1=value1
ENV_VAR_2=value2

Note

Values set in a skaffold.env file will not overwrite existing environment variables in the process.

Setting Skaffold Flags with Environment Variables

In addition to loading environment variables from the skaffold.env file, Skaffold also allows users to set flags using environment variables. To set a flag using an environment variable, use the SKAFFOLD_ prefix and convert the flag name to uppercase.

For example, to set the --cache-artifacts flag to true, the equivalent environment variable would be SKAFFOLD_CACHE_ARTIFACTS=true.

Here is an example usage in the skaffold.env file:

SKAFFOLD_CACHE_ARTIFACTS=true
SKAFFOLD_NAMESPACE=mynamespace

Note

If a flag is set both in the skaffold.env file and as a command line argument, the value specified in the command line argument will take precedence.

Docs: Local Cluster

Mon, 01 Jan 0001 00:00:00 +0000

Skaffold supports fast deployments to supported locally-hosted clusters, such as minikube and Docker Desktop, by loading images directly into the cluster. Loading images is typically much faster than the roundtrip required to push an image to a remote registry and then for the cluster to pull that image again.

Auto detection

Skaffold’s heuristic to detect local clusters is based on the Kubernetes context name set on kubectl. You can find your the current context name by running:

kubectl config current-context

Skaffold checks for the following context names:

Kubernetes context	Local cluster type	Notes
docker-desktop	`Docker Desktop`
docker-for-desktop	`Docker Desktop`	This context name is deprecated
minikube ¹	`minikube`	See ¹
kind-(.*)	`kind`	This pattern is used by kind >= v0.6.0
(.*)@kind	`kind`	This pattern was used by kind < v0.6.0
k3d-(.*)	`k3d`	This pattern is used by k3d >= v3.0.0

For any other name, Skaffold assumes that the cluster is remote and that images have to be pushed.

¹ Additionally, a Kubernetes context may be considered as minikube even if it’s not named minikube but it’s cluster certificate is stored at $HOME/.minikube or the minikube profile list command returns the Kubernetes context name.

Manual override

For non-standard local setups, such as a custom minikube profile, some extra configuration is necessary. The essential steps are:

Ensure that Skaffold builds the images with the same docker daemon that runs the pods’ containers.
Tell Skaffold to skip pushing images either by configuring
```
build:
  local:
    push: false
```
or by marking a Kubernetes context as local (see the following example).

For example, when running minikube with a custom profile (e.g. minikube start -p my-profile):

Set up the docker environment for Skaffold with source <(minikube docker-env -p my-profile). This should set some environment variables for docker (check with env | grep DOCKER). It is important to do this in the same shell where Skaffold is executed.
Tell Skaffold that the Kubernetes context my-profile refers to a local cluster with
```
skaffold config set --kube-context my-profile local-cluster true
```

Caveats

There are some caveats to note with local clusters.

Minikube has a separate Docker Daemon

Minikube has a separate Docker daemon that runs inside the minikube virtual machine, which is independent of the Docker installation that may be running on the host. Skaffold automatically uses minikube docker-env to configure image builders to use this internal Docker daemon as it results in a dramatic speed-up as compared to other approaches.

The use of minikube’s internal daemon does means that images are not available from the host’s daemon:

# build the image `skaffold-example`
$ skaffold build
...
Starting build...
Found [minikube] context, using local docker daemon.
...
Successfully tagged skaffold-example:v1.35.0-37-g7ccebe58e
Build [skaffold-example] succeeded

# but the image is not found in the host docker!
$ docker images skaffold-example
REPOSITORY   TAG       IMAGE ID   CREATED   SIZE

You must instead configure the Docker CLI to use the Minikube daemon:

$ minikube docker-env
export DOCKER_HOST="tcp://127.0.0.1:54168"
...
$ eval $(minikube docker-env) && docker images skaffold-example
REPOSITORY         TAG                                                                IMAGE ID       CREATED       SIZE
skaffold-example   160fe3a3c1358ef7b3fbfd1ae19fc8c5ac096635c39171e22ad1e5242b6ad8fd   160fe3a3c135   3 weeks ago   7.43MB
skaffold-example   v1.35.0-37-g7ccebe58e                                              160fe3a3c135   3 weeks ago   7.43MB

Minikube also offers a set of helper commands to manage images through minikube image.

Impacts of `imagePullPolicy`

Skaffold’s direct loading of images into a local cluster does mean that resources specifying an imagePullPolicy: Always may fail as the images are not be pushed to the remote registry.

Docs: Image Repository Handling

Mon, 01 Jan 0001 00:00:00 +0000

Often, a Kubernetes manifest (or skaffold.yaml) makes references to images that push to registries that we might not have access to. Modifying these individual image names manually is tedious, so Skaffold supports automatically prefixing these image names with a registry specified by the user. Using this, any project configured with Skaffold can be run by any user with minimal configuration, and no manual YAML editing!

This is accomplished through the default-repo functionality, and can be used one of three ways:

--default-repo flag
```
skaffold dev --default-repo <myrepo>
```

SKAFFOLD_DEFAULT_REPO environment variable

SKAFFOLD_DEFAULT_REPO=<myrepo> skaffold dev

Skaffold’s global config

skaffold config set default-repo <myrepo>

If no default-repo is provided by the user, there is no automated image name rewriting, and Skaffold will try to push the image as provided in the yaml.

The image name rewriting strategies are designed to be conflict-free: the full image name is rewritten on top of the default-repo so similar image names don’t collide in the base namespace (e.g.: repo1/example and repo2/example would collide in the target_namespace/example without this)

Automated image name rewriting strategies are determined based on the default-repo and the original image repository:

default-repo domain does not contain gcr.io or -docker.pkg.dev

strategy: escape & concat & truncate to 256

 original image: 	gcr.io/k8s-skaffold/skaffold-example1
 default-repo:      aws_account_id.dkr.ecr.region.amazonaws.com
 rewritten image:   aws_account_id.dkr.ecr.region.amazonaws.com/gcr_io_k8s-skaffold_skaffold-example1

default-repo contain gcr.io or -docker.pkg.dev (special cases - as GCR and AR allow for arbitrarily deep directory structure in image repo names)

strategy: concat unless prefix matches

example1: prefix doesn’t match:

  original image: 	gcr.io/k8s-skaffold/skaffold-example1
  default-repo: 	gcr.io/myproject/myimage
  rewritten image:  gcr.io/myproject/myimage/gcr.io/k8s-skaffold/skaffold-example1

example2: prefix matches:

  original image: 	gcr.io/k8s-skaffold/skaffold-example1
  default-repo: 	gcr.io/k8s-skaffold
  rewritten image:  gcr.io/k8s-skaffold/skaffold-example1

example3: shared prefix:

  original image: 	gcr.io/k8s-skaffold/skaffold-example1
  default-repo: 	gcr.io/k8s-skaffold/myimage
  rewritten image:  gcr.io/k8s-skaffold/myimage/skaffold-example1

Insecure image registries

During development you may be forced to push images to a registry that does not support HTTPS. By itself, Skaffold will never try to downgrade a connection to a registry to plain HTTP. In order to access insecure registries, this has to be explicitly configured per registry name.

There are several levels of granularity to allow insecure communication with some registry:

Per Skaffold run via the repeatable --insecure-registry flag

skaffold dev --insecure-registry insecure1.io --insecure-registry insecure2.io

Per Skaffold run via SKAFFOLD_INSECURE_REGISTRY environment variable

SKAFFOLD_INSECURE_REGISTRY='insecure1.io,insecure2.io' skaffold dev

Per project via the Skaffold pipeline config skaffold.yaml

build:
    insecureRegistries:
    - insecure1.io
    - insecure2.io

Per user via Skaffold’s global config

skaffold config set insecure-registries insecure1.io           # for the current kube-context
skaffold config set --global insecure-registries insecure2.io  # for any kube-context

Note that multiple set commands add to the existing list of insecure registries. To clear the list, run skaffold config unset insecure-registries.

Skaffold will join the lists of insecure registries, if configured via multiple sources.

Docs: Profiles

Mon, 01 Jan 0001 00:00:00 +0000

Skaffold profiles allow you to define build, test and deployment configurations for different contexts. Different contexts are typically different environments in your app’s lifecycle, like Production or Development.

You can create profiles in the profiles section of skaffold.yaml.

For a detailed discussion on Skaffold configuration, see Skaffold Concepts and skaffold.yaml References.

Profiles (`profiles`)

Each profile has six parts:

Name (name): The name of the profile
Build configuration (build)
Test configuration (test)
Deploy configuration (deploy)
Patches (patches)
Activation (activation)

Once a profile is activated, the specified build, test and deploy configuration in it will be laid onto, but won’t completely replace, the build, test and deploy sections declared in the main section of skaffold.yaml. The build, test and deploy configuration in the profiles section use the same syntax as the build, test and deploy sections of skaffold.yaml; for more information, see Builders, Testers, Deployers and you can always refer to skaffold.yaml reference for an overview of the syntax. Alternatively, you can override the main configuration with finer grained control using patches.

Activation

You can activate a profile two ways: CLI flag or skaffold.yaml activations.

CLI flag: You can activate profiles with the -p (--profile) parameter in the skaffold dev and skaffold run commands.

skaffold run -p [PROFILE]

Activations in skaffold.yaml: You can auto-activate a profile based on

kubecontext (could be either a string or a regexp: prefixing with ! will negate the match)
environment variable value
skaffold command (dev/run/build/deploy)

A profile is auto-activated if any one of the activations under it are triggered. An activation is triggered if all of the criteria (env, kubeContext, command) are triggered.

In the example below:

profile1 is activated if MAGIC_VAR is 42
profile2 is activated if MAGIC_VAR is 1337 or we are running skaffold dev while kubecontext is set to minikube.

build:
  artifacts:
  - image: gcr.io/k8s-skaffold/skaffold-example
manifests:
  rawYaml:
  - k8s-pod
profiles:
- name: profile1
  activation:
    - env: MAGIC_VAR=42
- name: profile2
  activation:
    - env: MAGIC_VAR=1337
    - kubeContext: minikube
      command: dev

Override via replacement

The build, test and deploy sections defined in the profile will be laid onto the main configuration. The default values are the same in profiles as in the main config.

The following example showcases a skaffold.yaml with one profile named gcb, for building with Google Cloud Build:

build:
  artifacts:
  - image: gcr.io/k8s-skaffold/skaffold-example
manifests:
  rawYaml:
  - k8s-pod
profiles:
- name: gcb
  build:
    googleCloudBuild:
      projectId: k8s-skaffold

With no profile activated, Skaffold will build the artifact gcr.io/k8s-skaffold/skaffold-example using local Docker daemon and deploy it with kubectl.

However, if you run Skaffold with the following command:

skaffold dev -p gcb

Skaffold will switch to Google Cloud Build for building artifacts.

Note that since the gcb profile does not specify a deploy configuration, Skaffold will continue using kubectl for deployments.

Override via patches

Patches are a more verbose way of overriding your config, but they provide a powerful, fine-grained way to override individual values in your yaml config. They are based on JSON Patch under the hood.

In the example below instead of overriding the whole build section, the dev profile specifically defines a different Dockerfile to use for the first artifact.

build:
  artifacts:
    - image: gcr.io/k8s-skaffold/skaffold-example
      docker:
        dockerfile: Dockerfile
    - image: gcr.io/k8s-skaffold/skaffold2
    - image: gcr.io/k8s-skaffold/skaffold3
manifests:
  rawYaml:
  - k8s-pod
profiles:
  - name: dev
    patches:
      - op: replace
        path: /build/artifacts/0/docker/dockerfile
        value: Dockerfile_dev

Activating multiple profiles at the same time

Multiple profiles can be specified either by using the -p flag multiple times or by comma separated profiles.

skaffold dev -p hello,world

Skaffold will activate both profiles, hello and world. This is e.g. useful when combined with patches to provide a composable development setup where hello and world can be added on demand.

Deactivating Profiles

Profiles can also be manually deactivated by prefixing the profile name with - like so:

skaffold dev -p hello,-world

Skaffold will activate the hello profile, and deactivate the world profile, even if it had otherwise been activated through the configuration.

Docs: Kube-context Activation

Mon, 01 Jan 0001 00:00:00 +0000

When interacting with a Kubernetes cluster, just like any other Kubernetes-native tool, Skaffold requires a valid Kubernetes context to be configured. The selected kube-context determines the Kubernetes cluster, the Kubernetes user, and the default namespace. By default, Skaffold uses the current kube-context from your kube-config file.

You can override this default one of two ways:

--kube-context flag
```
skaffold dev --kube-context <myrepo>
```
Specify deploy.kubeContext configuration in skaffold.yaml
```
deploy:
  kubeContext: minikube
```

The CLI flag always takes precedence over the config field in the skaffold.yaml.

Kube-context activation and Skaffold profiles

The kube-context has a double role for Skaffold profiles:

A Skaffold profile may be auto-activated by the current kube-context (via profiles.activation.kubeContext).
A Skaffold profile may change the kube-context (via profiles.deploy.kubeContext).

Skaffold ensures that these two roles are not conflicting. To that end, profile activation is done with the original kube-context. If any profile is auto-activated by a matching kube-context, the resulting kube-context must remain unchanged. This rule prevents profile-specific settings for one context to be deployed into a different context.

For example, given the following profiles:

profiles:
  - name: profile-1
    deploy:
      kubeContext: docker-for-desktop

  - name: profile-2
    activation:
      - kubeContext: minikube

It is illegal to activate both profiles here, because profile-2 has an activation by kube-context and profile-1 changes the effective kube-context. This happens for

skaffold run -p profile-1,profile-2
skaffold run -p profile-1 if the current kube-context is minikube

Note

It is possible to activate conflicting profiles in conjunction with the CLI flag. So the following example is valid skaffold run --kube-context minikube -p profile-1,profile-2

Limitations

It is not possible to change the kube-context of a running skaffold dev session. To pick up the changes to kubeContext, you will need to quit and re-run skaffold dev.

Kubeconfig selection

The kubeconfig file is only loaded once during Skaffold’s startup phase.

If the --kubeconfig flag is set, then only that file is loaded.
If $KUBECONFIG environment variable is set, then it is used as a list of paths (normal path delimiting rules for your system). These paths are merged.
Otherwise, ${HOME}/.kube/config is used.
If neither --kubeconfig or --kube-context are given and no kubeconfig file is found, Skaffold will try to guess an in-cluster configuration using the secrets stored in /var/run/secrets/kubernetes.io/serviceaccount/. This is useful when Skaffold runs inside a kubernetes Pod and should deploy to the same cluster.

Docs: Templated Fields

Mon, 01 Jan 0001 00:00:00 +0000

Skaffold allows for certain fields in the config to be templated via the Go text/template package. Environment variables and certain special values computed by Skaffold (see below) are available in the templating context (defined as “dot” or .).

Go templates are quite powerful, including control flow, arguments, pipelining and variables. Predefined functions in the standard library are complemented in Skaffold by the Sprig template function library.

build:
  tagPolicy:
    envTemplate:
      template: "{{.FOO}}"
  artifacts:
  - image: gcr.io/k8s-skaffold/example

Suppose the value of the FOO environment variable is v1, the image built will be gcr.io/k8s-skaffold/example:v1.

List of fields that support templating:

build.artifacts[].docker.buildArgs (see builders)
build.artifacts[].ko.{env,flags,labels,ldflags} (see ko builder)
build.tagPolicy.envTemplate.template (see envTemplate tagger)
deploy.helm.releases[].chartPath (see Deploying with helm)
deploy.helm.releases[].name (see Deploying with helm)
deploy.helm.releases[].namespace (see Deploying with helm)
deploy.helm.releases[].repo (see Deploying with helm)
deploy.helm.releases[].setValueTemplates (see Deploying with helm)
deploy.helm.releases[].version (see Deploying with helm)
deploy.helm.releases.valuesFiles (see Deploying with helm)
deploy.kubectl.defaultNamespace
deploy.kustomize.defaultNamespace
manifests.kustomize.paths.[]
manifests.helm.releases[].setValueTemplates
portForward.namespace
portForward.resourceName

Please note, this list is not exhaustive.

List of variables that are available for templating:

all environment variables passed to the Skaffold process at startup
For the envTemplate tagger:
- IMAGE_NAME - the artifact’s image name - the image name rewriting acts after the template is calculated
For Helm deployments:
- IMAGE_NAME, IMAGE_TAG, IMAGE_DIGEST, IMAGE_DOMAIN, IMAGE_REPO_NO_DOMAIN - the first (by order of declaration in build.artifacts) artifact’s image name, repo, tag, sha256 digest, registry/domain and repository w/o the registry/domain prefixed . Note: the image name rewriting acts after the template is calculated.
- IMAGE_NAME_<artifact-name>, IMAGE_REPO_<artifact-name>, IMAGE_TAG_<artifact-name>, IMAGE_DIGEST_<artifact-name> - the named artifact’s image name, repo, tag, and sha256 digest. NOTE: When used in for templating all / and - chars must be changed to _ characters as go templates do not accept / and -.
- IMAGE_NAME2, IMAGE_REPO2, IMAGE_TAG2, IMAGE_DIGEST2 - the 2nd artifact’s image name, tag, and sha256 digest
- IMAGE_NAME<N>, IMAGE_REPO<N>, IMAGE_TAG<N>, IMAGE_DIGEST<N> - the Nth artifact’s image name, tag, and sha256 digest

Local template functions

In addition to the functions listed above, Skaffold locally provides the following:

cmd: This allows users to use the result from external commands in template, for example {{cmd "bash" "-c" "xxx xxx xxx"}} can be used to execute bash script and get the result into the template.

Usage Examples

The templating pipelines provided by Go templates can be quite comprehensive when combined with Sprig. For example:

The environment variable SOURCE_DATE_EPOCH commonly specifies a UNIX timestamp to be used in replacement of the current date and time in compiler __DATE__ and __TIME__ macros, so that the embedded timestamps become reproducible. A numeric UNIX timestamp is less readable than a proper date, and the environment variable may not exist at all, in which case we would want to use the current date. This could be written as:

default now .SOURCE_DATE_EPOCH | date "2006-01-02T15:04:05-0700"
The idiomatic seven-character abbreviated Git hash is easily accessible:

cmd "bash" "-c" "git rev-parse HEAD" | substr 0 7

Skaffold – Environment Management

Docs: Load environment variables from a file

Note

Setting Skaffold Flags with Environment Variables

Note

Docs: Local Cluster

Auto detection

Manual override

Caveats

Minikube has a separate Docker Daemon

Impacts of imagePullPolicy

Docs: Image Repository Handling

Insecure image registries

Docs: Profiles

Profiles (profiles)

Activation

Override via replacement

Override via patches

Activating multiple profiles at the same time

Deactivating Profiles

Docs: Kube-context Activation

Kube-context activation and Skaffold profiles

Note

Limitations

Kubeconfig selection

Docs: Templated Fields

List of fields that support templating:

List of variables that are available for templating:

Local template functions

Usage Examples

Impacts of `imagePullPolicy`

Profiles (`profiles`)