Repository: jina-ai/serve
Pull request: docs: adjust port args
# Adjust ports arguments in docs

## Description

This changes the arguments `port-expose` and `port-in` in the documentation to just `port` as changed in the code [here](https://github.com/jina-ai/jina/pull/4382). 
As the docs are not versioned, only merge and deploy this change AFTER THE NEXT RELEASE.

Closes https://github.com/jina-ai/jina/issues/4367

Problem statement:
Unify port_expose and port_in
We have `port_expose` and `port_in` arguments for historical reasons, but we don't have the need anymore to distinguish between the two. Every Jina Pod only exposes a single port.
Thus we should unify the two arguments into a new argument, which is only called `port`. This needs to be done in a backwards compatible fashion, so make sure to deprecate the old arguments, but dont remove them.

This feature will go in the next release, so dont update the docs before the next release.

What needs to be done in this issue:

- [x] Add the new `port` argument and make sure it is used everywhere instead of `port_in` and `port_expose`. Make sure that docker-compose and K8s configuration generation is correct and does not generate the deprecated `port_in` and `port_expose`.
- [x] Make `port_in` and `port_expose` set the new `port` argument only and deprecate them.
- [x] Update all the tests defining port arguments
- [x] Prepare a separate PR against the docs to replace the port usage there. But only merge this AFTER the next release (to not update the docs prematurely) (Make sure that the docs state from which version the usage changed)

Hints from issue discussion:

Commit message: docs: adjust port args

Patch to review:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a2eaad9998544..77979d878e31b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10287,7 +10287,7 @@ Jina is released on every Friday evening. The PyPi package and Docker Image will
 
 ### 🐞 Bug fixes
 
- - [[```0147ad76```](https://github.com/jina-ai/jina/commit/0147ad769bbcd8c2181083b2aade4eece82d1b3d)] __-__ __script__: fix port_expose in jinad (*Han Xiao*)
+ - [[```0147ad76```](https://github.com/jina-ai/jina/commit/0147ad769bbcd8c2181083b2aade4eece82d1b3d)] __-__ __script__: fix port in jinad (*Han Xiao*)
  - [[```cb16849f```](https://github.com/jina-ai/jina/commit/cb16849fd4be8972e722b613632064f76352a0ee)] __-__ __dam__: warning truncate doc id (#3264) (*felix-wang*)
  - [[```fa444fa9```](https://github.com/jina-ai/jina/commit/fa444fa9009cc584d8325a12436665174da1cd73)] __-__ __ci__: fixed benchmark ci (#3285) (*Maksudur Rahman Maateen*)
  - [[```07f7636d```](https://github.com/jina-ai/jina/commit/07f7636d3c6e3a7d20ad71441f340e589e7090f4)] __-__ fix multiple import problem (#3276) (*Joan Fontanals*)
diff --git a/README.md b/README.md
index 0853b5176bcf0..ce940823a8d57 100644
--- a/README.md
+++ b/README.md
@@ -120,7 +120,7 @@ Preliminaries: <a href="https://pytorch.org/get-started/locally/">install PyTorc
 5. Connect all `Executor`s in a `Flow`, scale embedding to 3:
     ```python
     f = (
-        Flow(port_expose=12345)
+        Flow(port=12345)
         .add(uses=PreprocImg)
         .add(uses=EmbedImg, replicas=3)
         .add(uses=MatchImg)
@@ -276,7 +276,7 @@ You can containerize the Executors and use them in a sandbox thanks to [Hub](htt
 
     ```python
     f = (
-        Flow(port_expose=12345)
+        Flow(port=12345)
         .add(uses='jinahub+docker://1ylut0gf')
         .add(uses='jinahub+docker://258lzh3c')
     )
diff --git a/docs/fundamentals/flow/client.md b/docs/fundamentals/flow/client.md
index 2814f91a5c177..b03e8eead8baf 100644
--- a/docs/fundamentals/flow/client.md
+++ b/docs/fundamentals/flow/client.md
@@ -15,9 +15,9 @@ Starting the Flow:
 ```python
 from jina import Flow
 
-PORT_EXPOSE = 12345
+port = 12345
 
-with Flow(port_expose=PORT_EXPOSE) as f:
+with Flow(port=port) as f:
     f.block()
 ```
 
@@ -65,7 +65,7 @@ from docarray import Document, DocumentArray
 from jina import Flow, Client
 
 with Flow() as f:
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     client.post('/', DocumentArray(Document() for _ in range(100)), request_size=10)
 ```
 
@@ -96,7 +96,7 @@ f = (
 )
 
 with f:  # Using it as a Context Manager will start the Flow
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     docs = client.post(on='/', target_executor='barExecutor')
     print(docs.texts)
 ```
@@ -121,7 +121,7 @@ class MyExecutor(Executor):
 f = Flow().add(uses=MyExecutor)
 
 with f:
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     client.post('/', Document(), parameters={'hello': 'world'})
 ```
 
@@ -131,7 +131,7 @@ You can send a parameters-only data request via:
 
 ```python
 with f:
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     client.post('/', parameters={'hello': 'world'})
 ```
 
@@ -213,7 +213,7 @@ def beep(*args):
 
 
 with Flow().add() as f, open('output.txt', 'w') as fp:
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     client.post(
         '/',
         Document(),
@@ -249,7 +249,7 @@ from jina import Flow, Client
 from docarray import Document
 
 with Flow() as f:
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     docs = client.post(on='', inputs=Document(text='Hi there!'))
     print(docs)
     print(docs.texts)
@@ -267,7 +267,7 @@ from jina import Flow, Client
 from docarray import Document
 
 with Flow() as f:
-    client = Client(port=f.port_expose, return_responses=True)
+    client = Client(port=f.port, return_responses=True)
     resp = client.post(on='', inputs=Document(text='Hi there!'))
     print(resp)
     print(resp[0].docs.texts)
@@ -285,7 +285,7 @@ from jina import Flow, Client
 from docarray import Document
 
 with Flow() as f:
-    client = Client(port=f.port_expose)
+    client = Client(port=f.port)
     resp = client.post(
         on='',
         inputs=Document(text='Hi there!'),
@@ -328,6 +328,6 @@ async def run_client(port):
 
 
 with Flow() as f:  # Using it as a Context Manager will start the Flow
-    asyncio.run(run_client(f.port_expose))
+    asyncio.run(run_client(f.port))
 ```
 
diff --git a/docs/fundamentals/flow/create-flow.md b/docs/fundamentals/flow/create-flow.md
index 73ac9bc366826..2b347f92603cb 100644
--- a/docs/fundamentals/flow/create-flow.md
+++ b/docs/fundamentals/flow/create-flow.md
@@ -363,7 +363,7 @@ Those Executors are marked with the `external` keyword when added to a `Flow`:
 ```python
 from jina import Flow
 
-Flow().add(host='123.45.67.89', port_in=12345, external=True)
+Flow().add(host='123.45.67.89', port=12345, external=True)
 ```
 This is adding an external Executor to the Flow. The Flow will not start or stop this Executor and assumes that is externally managed and available at `123.45.67.89:12345`
 
diff --git a/docs/fundamentals/flow/flow-api.md b/docs/fundamentals/flow/flow-api.md
index f61e8bb165bcc..103b89ffe2f78 100644
--- a/docs/fundamentals/flow/flow-api.md
+++ b/docs/fundamentals/flow/flow-api.md
@@ -25,7 +25,7 @@ class FooExecutor(Executor):
         docs.append(Document(text='foo was here'))
 
 
-f = Flow(protocol='grpc', port_expose=12345).add(uses=FooExecutor)
+f = Flow(protocol='grpc', port=12345).add(uses=FooExecutor)
 with f:
     client = Client(port=12345)
     docs = client.post(on='/')
@@ -45,7 +45,7 @@ class FooExecutor(Executor):
         docs.append(Document(text='foo was here'))
 
 
-f = Flow(protocol='http', port_expose=12345).add(uses=FooExecutor)
+f = Flow(protocol='http', port=12345).add(uses=FooExecutor)
 with f:
     client = Client(port=12345, protocol='http')
     docs = client.post(on='/')
@@ -71,7 +71,7 @@ class FooExecutor(Executor):
         docs.append(Document(text='foo was here'))
 
 
-f = Flow(protocol='websocket', port_expose=12345).add(uses=FooExecutor)
+f = Flow(protocol='websocket', port=12345).add(uses=FooExecutor)
 with f:
     client = Client(port=12345, protocol='websocket')
     docs = client.post(on='/')
@@ -98,7 +98,7 @@ class EndpointExecutor(Executor):
         docs.append(Document(text='bar was called'))
 
 
-f = Flow(protocol='grpc', port_expose=12345).add(uses=EndpointExecutor)
+f = Flow(protocol='grpc', port=12345).add(uses=EndpointExecutor)
 with f:
     client = Client(port=12345)
     foo_response_docs = client.post(on='/foo')
diff --git a/docs/fundamentals/flow/index.md b/docs/fundamentals/flow/index.md
index 6c7d2f88293b7..426fad21015ba 100644
--- a/docs/fundamentals/flow/index.md
+++ b/docs/fundamentals/flow/index.md
@@ -69,7 +69,7 @@ class MyExecutor(Executor):
         print(docs)
 
 
-f = Flow(port_expose=12345).add(name='myexec1', uses=MyExecutor)
+f = Flow(port=12345).add(name='myexec1', uses=MyExecutor)
 
 with f:
     f.block()
diff --git a/docs/how-to/docker-compose.md b/docs/how-to/docker-compose.md
index a55c002741829..18dcabbbdaefc 100644
--- a/docs/how-to/docker-compose.md
+++ b/docs/how-to/docker-compose.md
@@ -54,7 +54,7 @@ neighbor retrieval on image embeddings.
 from jina import Flow
 
 f = (
-    Flow(port_expose=8080, protocol='http')
+    Flow(port=8080, protocol='http')
     .add(name='encoder', uses='jinahub+docker://CLIPImageEncoder', replicas=2)
     .add(
         name='indexer',
diff --git a/docs/how-to/external-executor.md b/docs/how-to/external-executor.md
index 9064550b02f0a..86095e00320ec 100644
--- a/docs/how-to/external-executor.md
+++ b/docs/how-to/external-executor.md
@@ -22,7 +22,7 @@ If you want to add an external Executor to your Flow, all you really need to kno
 You need:
 
 - `host`, the host address of the Executor
-- `port_in`, the port on which the Executor receives information
+- `port`, the port on which the Executor receives information
 
 Then, adding the Executor is a simple call to `Flow.add()` with the `external` argument set to True. This tells the Flow that
 it does not need to start the Executor itself.:
@@ -31,7 +31,7 @@ it does not need to start the Executor itself.:
 from jina import Flow
 
 exec_host, exec_port = 'localhost', 12345
-f = Flow().add(host=exec_host, port_in=exec_port, external=True)
+f = Flow().add(host=exec_host, port=exec_port, external=True)
 ```
 
 After that, the external Executor will behave just like an internal one. And you can even add the same Executor to multiple
@@ -63,7 +63,7 @@ Here we pick `12345`.
 ````{tab} Using Docker
 
 ```bash
-jina executor --uses jinahub+docker://CLIPTextEncoder --port-in 12345
+jina executor --uses jinahub+docker://CLIPTextEncoder --port 12345
 ```
 
 ````
@@ -71,7 +71,7 @@ jina executor --uses jinahub+docker://CLIPTextEncoder --port-in 12345
 ````{tab} Without Docker
 
 ```bash
-jina executor --uses jinahub://CLIPTextEncoder --port-in 12345
+jina executor --uses jinahub://CLIPTextEncoder --port12345
 ```
 
 ````
@@ -94,7 +94,7 @@ the following Flow in a Python file:
 ```python
 from jina import Flow
 
-f = Flow().add(host='localhost', port_in=12345, external=True)
+f = Flow().add(host='localhost', port=12345, external=True)
 ```
 
 Now we can encode our Documents:
@@ -154,7 +154,7 @@ This simply points Jina to our file and Executor class.
 Now we can run the CLI command again, this time using our custom Executor:
 
 ```bash
-jina executor --uses my-exec.yml --port-in 12345
+jina executor --uses my-exec.yml --port 12345
 ```
 
 Now that your Executor is up and running, we can tap into it just like before, and even use it from two different Flows.
@@ -163,8 +163,8 @@ Now that your Executor is up and running, we can tap into it just like before, a
 from jina import Flow
 from docarray import Document, DocumentArray
 
-f1 = Flow().add(host='localhost', port_in=12345, external=True)
-f2 = Flow().add(host='localhost', port_in=12345, external=True)
+f1 = Flow().add(host='localhost', port=12345, external=True)
+f2 = Flow().add(host='localhost', port=12345, external=True)
 with f1:
     f1.index(
         inputs=DocumentArray([Document(text='Greetings from Flow1') for _ in range(1)])
diff --git a/docs/how-to/kubernetes.md b/docs/how-to/kubernetes.md
index efd8ae17c1d37..e1b81f9cd6213 100644
--- a/docs/how-to/kubernetes.md
+++ b/docs/how-to/kubernetes.md
@@ -57,7 +57,7 @@ This example shows how to build and deploy a Flow in Kubernetes with [`CLIPImage
 from jina import Flow
 
 f = (
-    Flow(port_expose=8080)
+    Flow(port=8080)
     .add(name='encoder', uses='jinahub+docker://CLIPImageEncoder', replicas=2)
     .add(
         name='indexer',


Code review comments:
diff_hunk: @@ -10287,7 +10287,7 @@ Jina is released on every Friday evening. The PyPi package and Docker Image will
 
 ### 🐞 Bug fixes
 
- - [[```0147ad76```](https://github.com/jina-ai/jina/commit/0147ad769bbcd8c2181083b2aade4eece82d1b3d)] __-__ __script__: fix port_expose in jinad (*Han Xiao*)
+ - [[```0147ad76```](https://github.com/jina-ai/jina/commit/0147ad769bbcd8c2181083b2aade4eece82d1b3d)] __-__ __script__: fix port in jinad (*Han Xiao*)
path: CHANGELOG.md
text: @user1:
fix this, do not change changelog

diff_hunk: @@ -63,15 +63,15 @@ Here we pick `12345`.
 ````{tab} Using Docker
 
 ```bash
-jina executor --uses jinahub+docker://CLIPTextEncoder --port-in 12345
+jina executor --uses jinahub+docker://CLIPTextEncoder --port 12345
 ```
 
 ````
 
 ````{tab} Without Docker
 
 ```bash
-jina executor --uses jinahub://CLIPTextEncoder --port-in 12345
+jina executor --uses jinahub://CLIPTextEncoder --port12345
path: docs/how-to/external-executor.md
text: @user1:
space needed here