github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v2/design_proposals/configurable-transformable-allowlist.md (about)

     1  # Configurable transformableAllowList
     2  
     3  * Author(s): Ke Zhu (@shawnzhu)
     4  * Design Shepherd: Tejal Desai (tejal29)
     5  * Date: 2021-07-16
     6  * Status: Draft
     7  
     8  ## Objectives
     9  
    10  Configurable transformableAllowList for transforming manifests.
    11  
    12  ## Background
    13  
    14  Skaffold can only transform manifests from a non-extensible allowlist. When
    15  using any CRD out of this allowlist, skaffold can not transform it.
    16  
    17  Open issues concerning this problem:
    18  
    19  * Image not recognized in crd k8s manifest ([#4081](https://github.com/GoogleContainerTools/skaffold/issues/4081))
    20  
    21  There was comments out of the above issue to make this allowlist extensible.
    22  
    23  The goal of this document is to create an agreement on the configuration option
    24  and specification to extend `skaffold.kubernetes.manifest.transformableAllowList`.
    25  
    26  ## Design
    27  
    28  Add configuration `deploy.config.transformableAllowList` in `skaffold.yaml`:
    29  
    30  Notice that any new configuration option will be appended to existing allowlist. 
    31  
    32  ### Detailed discussion
    33  
    34  Option in `skaffold.yaml`
    35  
    36  ```YAML
    37  deploy:
    38    config:
    39      transformableAllowList:
    40      - type: pod # no group, implicitly all versions
    41      - type: batch/Job # group, implicitly all versions
    42      - type: openfaas.com/v1/Function
    43        image: [spec.image]
    44        labels: [spec.metadata.labels, spec.labels]    # https://www.openfaas.com/blog/manage-functions-with-kubectl/
    45      - type: apps/v1beta1/Deployment
    46        image: [spec.template.spec.initContainers.*.image, spec.template.spec.containers.*.image]
    47        labels: [spec.metadata.labels, spec.template.metadata.labels]
    48  ```
    49  
    50  The value of `type` field points to a resource type. So it's case sensitive
    51  and should support API groups and resource versions:
    52  
    53  * When not specifying group, it will transform given resource type of any group or versions.
    54  * When providing group but not resource version, it will transform given
    55  resource type of any versions.
    56  
    57  The value of `labels` field is a list of JSON-path-like paths to apply `labels`
    58  block to. If no `labels` field configured, it will simply apply `labels` block
    59  if missing.
    60  
    61  The value of `image` field is also a list of JSON-path-like paths to rewrite. If
    62  no `image` field configured, it will rewrite any field named `image`.
    63  
    64  ## Open issues/Questions
    65  
    66  Since it is an allowlist, neither options could disable transformation on any
    67  built-in resource like `ReplicaSet` or `Deployment`. However, it may need to
    68  refactor [current allowlist](https://github.com/GoogleContainerTools/skaffold/blob/27c38228ab929ddaf2636637b43f17fda1686652/pkg/skaffold/kubernetes/manifest/visitor.go#L28-L43).
    69  
    70  Is there any need to work out a deny list?
    71  
    72  ## Implementation plan
    73  
    74  1. `pkg/skaffold/schema/latest/config.go` - Add config option
    75  `transformableAllowList` to `DeployConfig`.
    76  2. `pkg/skaffold/kubernetes/manifest/visitor.go` - Refactor allowlist and add
    77  new parameter `transformableAllowList` to `*ManifestList.Visit()` by appending
    78  it to existing coded `transformableAllowList`
    79      - Support `labels` field
    80      - Support `image` field
    81  3. `pkg/skaffold/kubernetes/manifest/images.go` - Add new parameter to `*ManifestList.ReplaceImages()`
    82  to support given `transformableAllowList`
    83  4. Instrument each deployer to use the new parameter `transformableAllowList`
    84  
    85  ## Integration test plan
    86  
    87  Please describe what new test cases you are going to consider.
    88  
    89  1.  Unit and integration tests for `visitor.go`.
    90  
    91      The integration tests should be written to catch situations such as this
    92      configurable allowlist is either empty or empty array.
    93  
    94  3.  Document this new configuration option