github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v2/content/en/docs/custom-actions.md (about)

     1  ---
     2  title: "Custom Actions"
     3  linkTitle: "Custom Actions"
     4  weight: 48
     5  featureId: customactions
     6  ---
     7  
     8  With Skaffold you can define generic actions in a declarative way using a Skaffold config file (`skaffold.yaml`), and execute them with the `skaffold exec <action-name>` command.
     9  
    10  A generic action (a.k.a. Custom Action), defines a list of containers that will be executed in parallel when the action is invoked. A Custom Action execution is considered successful if all its containers end without errors, and considered as failed if one or more of its containers report an error.
    11  
    12  {{< alert title="Note">}}
    13  Custom Actions are meant to run **specific, completable tasks**; are not meant to be use to execute your main application.
    14  {{< /alert >}}
    15  
    16  ## Defining Custom Actions
    17  
    18  A Skaffold config file can define one or more Custom Actions using the [`customActions` stanza]({{< relref "/docs/references/yaml#customActions" >}}). Each action and container must be identified by an unique name across modules/configurations. **NOTE:** Two different [profiles]({{< relref "docs/environment/profiles" >}}) can have an action each, with the same name.
    19  
    20  Therefore, a configuration for a Custom Action named `update-infra`, with two containers, `update-db-schema` and `setup-external-proxy`, will be defined like this in a `skaffold.yaml` file:
    21  
    22  {{% readfile file="samples/custom-actions/two-local-actions.yaml" %}}
    23  
    24  Running `skaffold exec update-infra` with the previous configuration will trigger the execution of the `update-infra` action, as a [local (Docker) action]({{< relref "#local-docker" >}}), creating and running a container for `update-db-schema` (using the `gcr.io/my-registry/db-updater:latest` image), and `setup-external-proxy` (using the `gcr.io/my-registry/proxy:latest` image). The output will look like this:
    25  
    26  ```console
    27  $ skaffold exec update-infra
    28  Starting execution for update-infra
    29  ...
    30  [setup-external-proxy] updating proxy version...
    31  [setup-external-proxy] copying proxy rules...   
    32  [setup-external-proxy] starting proxy...
    33  [update-db-schema] starting db update...
    34  [update-db-schema] db schema update completed
    35  [setup-external-proxy] proxy configured
    36  ```
    37  
    38  To check the list of available options to configure an action please refer to the [`customActions` stanza documentation]({{< relref "/docs/references/yaml#customActions" >}}).
    39  
    40  ## Executing Custom Actions
    41  
    42  The `skaffold exec <action-name>` command will allow the execution of a defined Custom Action. During execution, Skaffold will stream the logs from the containers associated with the given action. If the execution of the action is successful, Skaffold will return a status code `0`, if it fails, it wil return `1`. To check the available options for the `skaffold exec` command, please refer to the [CLI documentation]({{< relref "/docs/references/cli/#skaffold-exec" >}}).
    43  
    44  ### Timeouts
    45  
    46  Per default, a Custom Action does not have a timeout configured, which means, the action will run until it completes (success or fail). Using the[ `customActions[].timeout`]({{< relref "/docs/references/yaml/#customActions-timeout" >}}) property you can change the previous behaviour, adding a desired timeout in seconds:
    47  
    48  {{% readfile file="samples/custom-actions/two-local-actions-timeout.yaml" %}}
    49  
    50  Running `skaffold exec update-infra` with the previous configuration will fail if the Custom Action takes more than 10 seconds to complete. If the timeout is triggered, Skaffold will stop any running container and will return a status code `1`:
    51  
    52  ```console
    53  $ skaffold exec update-infra
    54  tarting execution for update-infra
    55  ...
    56  [setup-external-proxy] updating proxy version...
    57  [setup-external-proxy] copying proxy rules...
    58  [setup-external-proxy] starting proxy...
    59  [update-db-schema] starting db update...
    60  context deadline exceeded
    61  ```
    62  
    63  Skaffold will return status code `0` if all the containers associated with the given action finish their execution before the 10 seconds timeout.
    64  
    65  ### Fail strategy
    66  
    67  A Custom Action will be run with a `fail-fast` strategy, which means, if one container associated with the action fails, Skaffold will stop any running container, and will return a status code `1`:
    68  
    69  The following `skaffold.yaml` config:
    70  
    71  {{% readfile file="samples/custom-actions/two-local-actions.yaml" %}}
    72  
    73  With an error in the `update-db-schema` container, will produce the following output:
    74  
    75  ```console
    76  $ skaffold exec update-infra
    77  Starting execution for update-infra
    78  ...
    79  [setup-external-proxy] updating proxy version...
    80  [setup-external-proxy] copying proxy rules...
    81  [setup-external-proxy] starting proxy...
    82  [update-db-schema] starting db update...
    83  "update-db-schema" running container image "gcr.io/my-registry/db-updater:latest" errored during run with status code: 1
    84  ```
    85  
    86  The previous default behaviour can be change with the [`customActions[].failFast` property]({{< relref "/docs/references/yaml/#customActions-failFast" >}}), changing its value to `false`:
    87  
    88  {{% readfile file="samples/custom-actions/local-action-fail-safe.yaml" %}}
    89  
    90  The previous configuration indicates Skaffold to run the `update-infra` action with a `fail-safe` strategy, which means, Skaffold will not interrupt any container if one or more of them fail; all the containers will run until they finish (success or fail):
    91  
    92  ```console
    93  Starting execution for update-infra
    94  ...
    95  [setup-external-proxy] updating proxy version...
    96  [setup-external-proxy] copying proxy rules...
    97  [setup-external-proxy] starting proxy...
    98  [update-db-schema] starting db update...
    99  [setup-external-proxy] proxy configured
   100  1 error(s) occurred:
   101  * "update-db-schema" running container image "gcr.io/my-registry/db-updater:latest" errored during run with status code: 1
   102  ```
   103  
   104  ### Execution modes
   105  
   106  A Custom Action has an execution mode associated with it that indicates Skaffold in which environment and how the containers of that action should be created and executed. This execution mode can be configured with the [`customActions[].executionMode` property]({{< relref "/docs/references/yaml/#customActions-executionMode" >}}). These are the available execution modes for a Custom Action:
   107  
   108  #### Local (Docker) - default {#local-docker}
   109  
   110  This is the default configuration when no [`customActions[].executionMode`]({{< relref "/docs/references/yaml/#customActions-executionMode" >}}) is specified. With this execution mode, Skaffold will run every container associated to a given Custom Action with a Docker daemon.
   111  
   112  #### Remote (K8s job)
   113  
   114  With this execution mode, Skaffold will create a K8s job for each container associated with the given action. For the following configuration:
   115  
   116  {{% readfile file="samples/custom-actions/k8s-action.yaml" %}}
   117  
   118  Skaffold will create one K8s job for `update-db-schema` and another for `setup-external-proxy`. The jobs will use the following template per default:
   119  
   120  ```yaml
   121  apiVersion: batch/v1
   122  kind: Job
   123  metadata:
   124    name: # <- Container name defined in skaffold.yaml.
   125  spec:
   126    template:
   127      spec:
   128        containers: # <- Only one container, the one defined in the skaffold.yaml.
   129        # ...
   130        restartPolicy: Never
   131    backoffLimit: 0
   132  ```
   133  
   134  The template can be extended using the [`customActions[].executionMode.kubernetesCluster.overrides`]({{< relref "/docs/references/yaml/#customActions-executionMode-kubernetesCluster-overrides" >}}) and [`customActions[].executionMode.kubernetesCluster.jobManifestPath`]({{< relref "/docs/references/yaml/#customActions-executionMode-kubernetesCluster-jobManifestPath" >}}) properties.
   135  
   136  ## Skaffold build + exec
   137  
   138  Custom Actions can be used together with [Skaffold build]({{< relref "docs/builders/" >}}) so the Custom Actions can use images build by Skaffold. 
   139  
   140  Using the following `skaffold.yaml` file:
   141  
   142  {{% readfile file="samples/custom-actions/actions-local-build.yaml" %}}
   143  
   144  We trigger an Skaffold build using the `skaffold build` command:
   145  
   146  ```console
   147  $ skaffold build --file-output=build.json
   148  ```
   149  
   150  Skaffold will create a new `build.json` file with the necessary info. Then, using the generated file, we can run `skaffold exec`:
   151  
   152  ```console
   153  $ skaffold exec update-infra --build-artifacts=build.json
   154  ```
   155  
   156  That way, Skaffold will be able to run the `local-db-updater` image in the `update-infra` Custom Action.
   157