github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v1/content/en/docs/tutorials/skaffold-resource-selector.md (about)

     1  ---
     2  title: "Manage CRDs w/ Skaffold - Configuring Which K8s Resources & Fields Skaffold Manages"
     3  linkTitle: "Manage CRDs w/ Skaffold - Configuring Which K8s Resources & Fields Skaffold Manages"
     4  weight: 90
     5  featureId: skaffold-resource-selector
     6  aliases: [/docs/how-tos/skaffold-resource-selector]
     7  ---
     8  
     9  Common Use Cases This Page Helps Resolve:
    10  * Users who want skaffold to properly manage the rendering and deployment of their custom CRDs (as skaffold does with K8s objects like Pod, Deployment.apps, etc.)
    11    * Additionally users w/ a CRD that uses a different field name for `image:` (eg: `foo:`) and want skaffold to properly modify the value to instead have the image label for the image skaffold recently built
    12  * Users who are seeing issues with skaffold's default resource field overwriting for a given resource - eg: skaffold errors as it tries to mutate immutable config on re-deployment
    13  
    14  Currently skaffold modifies the manifests it renders and deploys for the following functionality:
    15  - status checking - done by mutating the manifest/K8s-Object by adding a label - skaffold/dev/run-id.  Skaffold uses this run-id to identify ... (TODO add doc link to run-id explanation)
    16  - image label overwriting - done by mutating the manifest/K8s-Object by substituting the `image:$ORIGINAL_IMAGE_TAG` value(s) in a manifest with `image:$RECENT_SKAFFOLD_BUILT_IMAGE`
    17  
    18  
    19  Skaffold has by default the following resources set for management via field "labels:" and "image:" overwriting:
    20  
    21  _The below list is derived from the values defined [here](https://github.com/GoogleContainerTools/skaffold/blob/main/pkg/skaffold/kubernetes/manifest/visitor.go)_
    22  
    23  
    24  * Pod
    25  * DaemonSet.apps
    26  * Deployment.apps
    27  * ReplicaSet.apps
    28  * StatefulSet.apps (with the exception of `.spec.volumeClaimTemplates.*.metadata.labels` field(s))
    29  * CronJob.batch
    30  * Job.batch
    31  * DaemonSet.extensions
    32  * Deployment.extensions
    33  * ReplicaSet.extension
    34  * Service.serving.knative.dev
    35  * Fleet.agones.dev
    36  * GameServer.agones.dev
    37  * Rollout.argoproj.io
    38  * Workflow.argoproj.io
    39  * CronWorkflow.argoproj.io
    40  * WorkflowTemplate.argoproj.io
    41  * ClusterWorkflowTemplate.argoproj.io
    42  * *.cnrm.cloud.google.com
    43  
    44  _This default overwriting modifies all JSON Paths for those GroupKinds of the form:_
    45  _* *.metadata.labels (skaffold appends a `run-id` label to existing labels or adds a `labels `field with a `run-id` entry if it didn't exist prior)_
    46  _* *.image (changes `image:` value to be the skaffold built image ONLY IF skaffold manages the original `image:` value)_
    47  
    48  
    49  The GroupKind's that Skaffold manages (via resource field overwriting) are user configurable via the `resourceSelector:` top level configuration.  The `resourceSelector` configuration allows users to modify and extend which resources and what fields of those resources skaffold modifies.  Currently skaffold only supports `label:` and `.metadata.labels` related modifications.
    50  (TODO add `resourceSelector` schema overview and allowable inputs)
    51  `resourceSelector` spec (from `pkg/skaffold/schema/latest/config.go`)
    52  ```
    53  // ResourceSelector describes user defined filters describing how skaffold should treat objects/fields during rendering.
    54  ResourceSelector ResourceSelectorConfig `yaml:"resourceSelector,omitempty"`
    55  
    56  // ResourceSelectorConfig contains all the configuration needed by the deploy steps.
    57  type ResourceSelectorConfig struct {
    58  	// Allow configures an allowlist for transforming manifests.
    59  	Allow []ResourceFilter `yaml:"allow,omitempty"`
    60  	// Deny configures an allowlist for transforming manifests.
    61  	Deny []ResourceFilter `yaml:"deny,omitempty"`
    62  }
    63  
    64  // ResourceFilter contains definition to filter which resource to transform.
    65  type ResourceFilter struct {
    66  	// GroupKind is the compact format of a resource type.
    67  	GroupKind string `yaml:"groupKind" yamltags:"required"`
    68  	// Image is an optional slice of JSON-path-like paths of where to rewrite images.
    69  	Image []string `yaml:"image,omitempty"`
    70  	// Labels is an optional slide of JSON-path-like paths of where to add a labels block if missing.
    71  	Labels []string `yaml:"labels,omitempty"`
    72  }
    73  ```
    74  
    75  The values for `Image` and `Labels` support a JSON Path style string which designates a path to a field in the speified GroupKind.  Additionally there is a special `.*` value that can be used which means that skaffold will attempt to overwrite all relevant labels following the below rules:
    76  - image: [".*"] -> replace all fields which follow `*.image:` where the value is an image that skaffold manages/builds
    77  - labels: [".*"] -> append-to or create a field named `*.metadata.labels` if a field `*.metadata` is found
    78  
    79  Some example use cases and motivations for the `resourceSelector` are shown below:
    80  * Skaffold Management of Custom CRD - The below snippet using `resourceSelector` allows a user to configure skaffold to manage a custom CRD (eg: CustomDeployment.skaffold.dev) they've created for their application in a skaffold.  
    81  
    82  _Without this snippet, skaffold would apply the yaml but would not properly wait for child resources or replace the `image:` values with skaffold built images_
    83  {{% readfile file="samples/resource-selector/resource-selector-crd-example.yaml" %}}
    84  
    85  Using the above configuation, skaffold will properly update the `image:` ... and .. allowing it to ... 
    86  
    87  * Fix Issue With Skaffold Overwriting Immutable Field - The below snippet using `resourceSelector` shows a user configuring skaffold to change it's behaviour to NOT overwrite a resource's field to prevent K8s errors related to overwriting an immutable field:
    88  _The below configuration is actually a part of skaffold's default configuration, just made into a snippet to use as an example_
    89  {{% readfile file="samples/resource-selector/resource-selector-deny-example.yaml" %}}
    90  
    91  * Allow `image:` Overwriting For Differently Named Image Field(s) - The below snippet using `resourceSelector` shows a user configuring skaffold to change it's behaviour to overwrite a resource's `foo:`field with skaffold built images.  This allows skaffold to properly support the images skaffold builds this resources which uses `foo:` instead of `image:` for an image value:
    92  {{% readfile file="samples/resource-selector/resource-selector-allow-example.yaml" %}}