github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v1/content/en/docs/design/config.md (about)

     1  ---
     2  title: "Skaffold Pipeline"
     3  linkTitle: "Skaffold Pipeline"
     4  weight: 40
     5  aliases: [/docs/concepts/config]
     6  ---
     7  
     8  You can configure Skaffold with the Skaffold configuration file,
     9  `skaffold.yaml`.  A single configuration consists of several different components:
    10  
    11  | Component  | Description |
    12  | ---------- | ------------|
    13  | `apiVersion` | The Skaffold API version you would like to use. The current API version is {{< skaffold-version >}}. |
    14  | `kind`  |  The Skaffold configuration file has the kind `Config`.  |
    15  | `metadata`  |  Holds additional properties like the `name` of this configuration.  |
    16  | `build`  |  Specifies how Skaffold builds artifacts. You have control over what tool Skaffold can use, how Skaffold tags artifacts and how Skaffold pushes artifacts. Skaffold supports using local Docker daemon, Google Cloud Build, Kaniko, or Bazel to build artifacts. See [Builders](/docs/pipeline-stages/builders) and [Taggers]({{< relref "/docs/pipeline-stages/taggers" >}}) for more information. |
    17  | `test` |  Specifies how Skaffold tests artifacts. Skaffold supports [container-structure-tests](https://github.com/GoogleContainerTools/container-structure-test) to test built artifacts and custom tests to run custom commands as part of the development pipeline. See [Testers]({{< relref "/docs/pipeline-stages/testers" >}}) for more information. |
    18  | `deploy` |  Specifies how Skaffold deploys artifacts. Skaffold supports using `kubectl`, `helm`, or `kustomize` to deploy artifacts. See [Deployers]({{< relref "/docs/pipeline-stages/deployers" >}}) for more information. |
    19  | `profiles`|  Profile is a set of settings that, when activated, overrides the current configuration. You can use Profile to override the `build`, `test` and `deploy` sections. |
    20  | `requires`|  Specifies a list of other skaffold configurations to import into the current config |
    21  
    22  You can [learn more]({{< relref "/docs/references/yaml" >}}) about the syntax of `skaffold.yaml`.
    23  
    24  Skaffold normally expects to find the configuration file as
    25  `skaffold.yaml` in the current directory, but the location can be
    26  overridden with the `--filename` flag.
    27  
    28  ### File resolution
    29  
    30  The Skaffold configuration file often references other files and
    31  directories.  These files and directories are resolved
    32  relative to the current directory _and not to the location of
    33  the Skaffold configuration file_.  There are two important exceptions:
    34  1. Files referenced from a build artifact definition are resolved relative to the build artifact's _context_ directory.
    35     When omitted, the context directory defaults to the current directory.
    36  2. For [configurations resolved as dependencies](#configuration-dependencies"), paths are always resolved relative to the directory containing the imported configuration file.
    37  
    38  For example, consider a project with the following layout:
    39  ```
    40  .
    41  ├── frontend
    42  │   └── Dockerfile
    43  ├── helm
    44  │   └── project
    45  │       └── dev-values.yaml
    46  └── skaffold.yaml
    47  ```
    48  
    49  The config file might look like:
    50  ```yaml
    51  apiVersion: skaffold/v2beta11
    52  kind: Config
    53  build:
    54    artifacts:
    55    - image: app
    56      context: frontend
    57      docker:
    58        dockerfile: "Dockerfile"
    59  deploy:
    60    helm:
    61      releases:
    62      - name: project
    63        chartPath: helm/project
    64        valuesFiles:
    65        - "helm/project/dev-values.yaml"
    66  ```
    67  
    68  In this example, the `Dockerfile` for building `app`
    69  is resolved relative to `app`'s context directory,
    70  whereas the the Helm chart's location and its values-files are
    71  relative to the current directory in `helm/project`.
    72  
    73  We generally recommend placing the configuration file in the root directory of the Skaffold project.
    74  
    75  ## Multiple configuration support
    76  
    77  A single `skaffold.yaml` file can define multiple skaffold configurations in the schema described above using the separator `---`. If these configuration objects define the `metadata.name` property then we consider them as `modules`, that can then be activated by name.
    78  
    79  Consider a `skaffold.yaml` defined as:
    80  
    81  ```yaml
    82  apiVersion: skaffold/vX
    83  kind: Config
    84  metadata:
    85    name: cfg1
    86  build:
    87    # build definition
    88  deploy:
    89    # deploy definition
    90  
    91  ---
    92  
    93  apiVersion: skaffold/vX
    94  kind: Config
    95  metadata:
    96    name: cfg2
    97  build:
    98    # build definition
    99  deploy:
   100    # deploy definition
   101  ```
   102  
   103  Here `cfg1` and `cfg2` are independent skaffold modules. Running `skaffold dev` for instance will execute actions from both these modules. You could also run `skaffold dev --module cfg1` to only activate the `cfg1` module and skip `cfg2`.
   104  
   105  ## Configuration dependencies
   106  
   107  In addition to authoring configurations in a `skaffold.yaml` file, we can also import other existing configurations as dependencies. Skaffold manages all imported and defined configurations in the same session. It also ensures all artifacts in a required config are built prior to those in current config (provided the artifacts have dependencies defined); and all deploys in required configs are applied prior to those in current config.
   108  
   109  {{< alert title="Note:" >}}
   110  Running `skaffold <command> --module <config-name>` will filter to the specified target module, but also include the transitive closure of all other configurations in its dependency graph. For instance, if a module `cfg1` imported another module `cfg2` as a dependency while `cfg2` imported `cfg3` and `cfg4`, then running `skaffold dev --module cfg1` would activate all of `cfg1`, `cfg2`, `cfg3` and `cfg4` and execute them in dependency order.
   111  {{< /alert >}}
   112  
   113  ### Local config dependency
   114  
   115  Consider the same `skaffold.yaml` defined above. Modules `cfg1` and `cfg2` from the above file can be imported as dependencies in your current config definition, via:
   116  
   117  ```yaml
   118  apiVersion: skaffold/v2beta11
   119  kind: Config
   120  requires:
   121    - configs: ["cfg1", "cfg2"]
   122      path: path/to/other/skaffold.yaml 
   123  build:
   124    # build definition
   125  deploy:
   126    # deploy definition
   127  ```
   128  
   129  If the `configs` list isn't defined then it imports all the configs defined in the file pointed by `path`. Additionally, if the `path` to the configuration isn't defined it assumes that all the required configs are defined in the same file as the current config.
   130  
   131  {{< alert title="Note:" >}}
   132  In imported configurations, files are resolved relative to the location of imported Skaffold configuration file.
   133  {{< /alert >}}
   134  
   135  ### Remote config dependency
   136  
   137  The required skaffold config can live in a remote git repository:
   138  
   139  ```yaml
   140  apiVersion: skaffold/v2beta12
   141  kind: Config
   142  requires:
   143    - configs: ["cfg1", "cfg2"]
   144      git:
   145        repo: http://github.com/GoogleContainerTools/skaffold.git
   146        path: getting-started/skaffold.yaml
   147        ref: main
   148  ```
   149  
   150  The environment variable `SKAFFOLD_REMOTE_CACHE_DIR` or flag `--remote-cache-dir` specifies the download location for all remote repos. If undefined then it defaults to `~/.skaffold/repos`. 
   151  The repo root directory name is a hash of the repo `uri` and the `branch/ref`.
   152  Every execution of a remote module resets the cached repo to the referenced ref. The default ref is `master`. If `master` is not defined then it defaults to `main`.
   153  The remote config gets treated like a local config after substituting the path with the actual path in the cache directory.
   154  
   155  ### Profile Activation in required configs
   156  
   157  Profiles specified by the `--profile` flag are also propagated to all  configurations imported as dependencies, if they define them. This behavior can be disabled by setting the `--propagate-profiles` flag to `false`.
   158  
   159  You can additionally set up more granular and conditional profile activations across dependencies through the `activeProfiles` stanza:
   160  
   161  ```yaml
   162  apiVersion: skaffold/v2beta11
   163  kind: Config
   164  metadata:
   165      name: cfg
   166  requires:
   167    - path: ./path/to/required/skaffold.yaml
   168      configs: [cfg1, cfg2]                 
   169      activeProfiles:                                     
   170       - name: profile1                               
   171         activatedBy: [profile2, profile3] 
   172  ```
   173  
   174  Here, `profile1` is a profile that needs to exist in both configs `cfg1` and `cfg2`; while `profile2` and `profile3` are profiles defined in the current config `cfg`. If the current config is activated with either `profile2` or `profile3` then the required configs `cfg1` and `cfg2` are imported with `profile1` applied. If the `activatedBy` clause is omitted then that `profile1` always gets applied for the imported configs.
   175  
   176  
   177  
   178  {{< alert title="Follow up" >}}
   179  Take a look at the [tutorial]({{< relref "/docs/tutorials/config-dependencies" >}}) section to see this in action.
   180  {{< /alert >}}