github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v2/design_proposals/port-forward.md (about)

     1  # Make Skaffold port-forwarding less surprising
     2  
     3  * Author(s): Brian de Alwis
     4  * Date: 2020-09-22
     5  * Late updated: 2021-03-16
     6  * Status: Reviewed/Cancelled/Under implementation/**Complete**
     7  
     8  ## Objective
     9  
    10  Align Skaffold port-forwarding behaviour with user expectations.
    11  
    12  
    13  ## Background
    14  
    15  Skaffold supports establishing port-forwarding to deployed Kubernetes resources through
    16  several mechanisms:
    17  
    18  - A user can configure one or more [port forwards in their `skaffold.yaml`](https://skaffold.dev/docs/references/yaml/#portForward)
    19    to connect a local port to a remote port on a pod, a service, or some workload resource that
    20    has a pod-spec (e.g., Deployment, ReplicaSet, Job).
    21  - Skaffold automatically configures port-forwards for services.
    22  - When in _debug_ mode (`skaffold debug`), Skaffold automatically configures port-forwards to pods too.
    23  
    24  Port-forwards are only established when a user runs Skaffold with `--port-forward`.  This was a conscious
    25  choice in [#969](https://github.com/GoogleContainerTools/skaffold/issues/969) as Skaffold had been
    26  forwarding all containerPorts defined on pods, and doing so led to conflicts
    27  in ports chosen.  Users with many services encountered confusion when dealing with many services
    28  ([#1564](https://github.com/GoogleContainerTools/skaffold/issues/1564)).
    29  
    30  But putting all port-forwards behind the `--port-forward` flag has resulted in new user confusion
    31  (e.g., [#4163](https://github.com/GoogleContainerTools/skaffold/issues/4163),
    32  [#4818](https://github.com/GoogleContainerTools/skaffold/issues/4818)):
    33  
    34  > *discr33t* 12:32 PM: I’m having a problem getting Skaffold to port-forward to my service after
    35  > doing a Helm deploy. If I use the --port-forward flag it will port-forward all my services. But
    36  > if I define portForward: anywhere in my `skaffold.yaml` nothing is working.
    37  
    38  Forwarding all `containerPort`s on pods in `skaffold debug` has also resulted in odd situations
    39  such as container-ports being allocated before service ports.  For example, the Skaffold
    40  [`examples/react-reload`](https://github.com/GoogleContainerTools/skaffold/tree/main/examples/react-reload/) example
    41  has a [service on port 8080](https://github.com/GoogleContainerTools/skaffold/tree/main/examples/react-reload/k8s/deployment.yaml#L7)
    42  and a [deployment/pod on port 8080](https://github.com/GoogleContainerTools/skaffold/blob/main/examples/react-reload/k8s/deployment.yaml#L29).
    43  
    44  
    45  
    46  ## Design
    47  
    48  This document proposes to change Skaffold port-forwarding's defaults in a similar fashion as proposed
    49  by @corneliusweig in https://github.com/GoogleContainerTools/skaffold/issues/1564#issuecomment-473528574.
    50  These changes are intended to be backwards-compatible with the previous version
    51  of Skaffold except where noted.
    52  
    53  
    54  ### Command-Line Changes
    55  
    56  > **NOTE**: Ideally we would re-purpose Skaffold's existing `--port-forward` CLI argument in
    57  > a backward-compatible manner (still under investigation).  This document assumes it is
    58  > not possible.
    59  
    60  Skaffold's `--port-forward` argument should be changed from a binary true/false option to
    61  a set of comma-separated values with the following defined modes:
    62  
    63     - `user`: user-defined port-forwards as defined in the `skaffold.yaml`
    64     - `services`: service ports are forwarded
    65     - `pods`: `containerPort`s defined on Pods and Kubernetes workload objects that have pod-specs
    66       are forwarded (Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob)
    67     - `debug`: an internal strategy to forward debugging-related ports on Pods as set up
    68       from `skaffold debug`
    69     - `off`: no ports are ever forwarded
    70  
    71  #### Changes to port-forwarding defaults
    72  
    73  Skaffold will default to enabling port-forwarding for establishing user-defined port-forwards
    74  as defined in the `skaffold.yaml`.  Skaffold's `dev` and `debug` will be changed to the following defaults.
    75  
    76  Command-line                        | v1.15.0 default modes          | New default modes
    77  ----------------------------------- | ---------------- | -------------------
    78  `skaffold dev`                        | off            | user
    79  `skaffold dev --port-forward`         | user, services | user, services (no change)
    80  `skaffold dev --port-forward=false`   | off            | off (no change)
    81  `skaffold debug`                      | off            | user, debug
    82  `skaffold debug --port-forward`       | user, services, pods | user, services, debug
    83  `skaffold debug --port-forward=false` | off            | off (no change)
    84  
    85  **Compatibility Change:** The behaviour of `skaffold debug --port-forward` no longer forwards all
    86  `containerPort`s defined on pods.  Container ports were forwarded as there was no other option to forward
    87  just debug ports.  With this proposed change, the `debug` mode will only select debug ports.  Forwarding all
    88  `containerPort`s was the cause of some confusion in earlier iterations of port-forwarding.
    89  
    90  
    91  ### Open Issues/Questions
    92  
    93  Please list any open questions here in the following format:
    94  
    95  **\<Question\>**
    96  
    97  Resolution: Please list the resolution if resolved during the design process or
    98  specify __Not Yet Resolved__
    99  
   100  
   101  ## Implementation plan
   102  
   103  1. Separate user-defined forwarding from [ResourceForwarder](https://github.com/GoogleContainerTools/skaffold/blob/main/pkg/skaffold/kubernetes/portforward/resource_forwarder.go)
   104  2. Amend `WatchingPodForwarder` to take a pod/port-filter to allow determining if a port is
   105     a debug port, as determined by the `debug.cloud.google.com` annotation.
   106  3. Somehow turn `--port-forward` into string slice argument, if possible!
   107  4. Add support to the skaffold.yaml schema
   108  5. Add support to the global configuration schema.
   109  
   110  ___
   111  
   112  
   113  ## Integration test plan
   114  
   115  Please describe what new test cases you are going to consider.
   116  
   117  1. `skaffold dev` should forward user-defined ports (no services, not container ports).
   118  2. `skaffold dev --port-forward` should forward services (no container ports).
   119  3. `skaffold dev --port-forward=off` should forward nothing.
   120  4. `skaffold dev --port-forward=X` for X={user,debug,pods,services}` should only forward those items.
   121  5. `skaffold debug` should forward user-defined ports and debug ports (no services, no other container ports).
   122  6. `skaffold debug --port-forward` should forward user-defined ports, debug ports, and services (no container ports).
   123  7. `skaffold debug --port-forward=off` should forward nothing.
   124  8. `skaffold debug --port-forward=X` for X={user,debug,pods,services}` should only forward those items.