From 99cb681f8d645069b3c2dd18f81da8cc0e6585f0 Mon Sep 17 00:00:00 2001 From: Dharmit Shah Date: Mon, 5 Sep 2022 16:57:28 +0530 Subject: [PATCH 1/5] Guide for migrating from v2 to v3 Signed-off-by: Dharmit Shah --- .../docs/user-guides/v3-migration-guide.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/website/docs/user-guides/v3-migration-guide.md diff --git a/docs/website/docs/user-guides/v3-migration-guide.md b/docs/website/docs/user-guides/v3-migration-guide.md new file mode 100644 index 00000000000..9cbf77fae7c --- /dev/null +++ b/docs/website/docs/user-guides/v3-migration-guide.md @@ -0,0 +1,88 @@ +--- +title: Migrate from v2 to v3 +sidebar_position: 2 +--- + +### Where are `odo push` and `odo watch` commands? +`odo push` and `odo watch` have been replaced in v3 by a single command - `odo dev`. It does the job of two commands +in a single command, and also allows the user to not watch if `--no-watch` flag is passed. + +In v2, if you wanted to automatically sync the code on developer system with the application running on a Kubernetes +cluster, you had to perform two steps - first `odo push` to start the application on the cluster, and second `odo watch` +to automatically sync the code. In v3, `odo dev` performs both actions with a single command. + +`odo dev` is not _just_ a replacement for these two commands. It's also different in behaviour in that, it's a +long-running process that's going to block the terminal. Hitting `Ctrl+c` will stop the process and cleanup the +component from the cluster. In v2, you had to use `odo delete`/`odo component delete` to delete inner loop resources +of the component from the cluster. + +### Migrate existing odo component from v2 to v3 +If you have created an odo component using odo v2, this section will help you move it to use odo v3. +1. `cd` into the component directory, and delete the component from the Kubernetes cluster: + ```shell + $ odo delete -f + ``` +2. Download and install odo v3 by following the steps mentioned [here](../overview/installation.md). +3. Use [`odo dev`](../command-reference/dev.md) to start developing your application using odo v3. + +If you face any problem, [open an issue on odo's repository](https://github.com/redhat-developer/odo/issues/new?assignees=&labels=&template=Bug.md). + +### Commands added, modified or removed in v3 + +The following table contains a list of odo commands that have either been modified or removed. In case of a +modification, the modified command is mentioned in the `v3` column. Please refer below legend beforehand: +* 👷 currently not implemented, but might get implemented in future +* ❌ not implemented, no plans for implementation + +| v2 | v3 | +|--------------|--| +| app delete | ❌ | +| app describe | ❌ | +| app list | ❌ | +| catalog describe service| ❌ | +| catalog describe component | registry --details | +| catalog list service | 👷odo list services | +| catalog list component | registry | +| catalog search service | ❌ | +| catalog search component | registry --filter | +| config set | ❌ | +| config unset | ❌ | +| config view | ❌ | +| debug info | ❌ (not needed as debug mode is start with odo dev --debug command that blocks terminal, the application can be running in inner-loop mode only if odo dev is running in terminal) | +| debug port-forward | ❌(port forwarding is automatic when users execute odo dev --debug) | +| env set | ❌ | +|env uset | ❌ | +| env view | ❌ | +|preference set| preference set| +|preference unset| preference unset| +|preference view| preference view| +|project create| create namespace| +|project delete| delete namespace| +|project get| ❌ | +|project list| list namespace| +|project set| set namespace| +|registry add| preference add registry| +|registry delete| preference remove registry| +|registry list| preference view | +| registry update|no command for update. If needed, it can be done using preference remove registry and preference add registry| +|service create/delete/describe/list|❌| +|storage create/delete/list|❌| +|test|👷(will be implemented after v3-GA) #6070| +|url create/delete/list| ❌ (odo dev automatically sets port forwarding between container and localhost. If users for some reason require Ingress or Route for inner-loop development they will have to explicitly define them in the devfile as kubernetes components)| +|build-images|build-images| +|deploy|deploy| +|login|login| +|logout|logout| +|create / component create|init| +|delete / component delete|delete component| +|describe / component describe|describe component| +|exec / component exec|❌| +|link / component link|add binding|list / component list| +|list|log / component log| +|logs|push / component push|in v3 there is only dev command that behaves more like watch in v2. There is an option to disable automatic reloads when a file is changed (--no-watch) in future there will be an option to trigger “sync” explicitly when --no-watch option is used)| +|status / component status|❌| +|unlink / component unlink|remove binding| +|watch / component watch|dev| +|❌|describe binding| +|❌|list binding| +|❌|analyze | \ No newline at end of file From 266d8570221642cabc78cd9c2a44a433156faad4 Mon Sep 17 00:00:00 2001 From: Dharmit Shah Date: Tue, 6 Sep 2022 19:50:27 +0530 Subject: [PATCH 2/5] Incorporate Armel's PR feedback Signed-off-by: Dharmit Shah --- .../docs/user-guides/v3-migration-guide.md | 32 ++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/website/docs/user-guides/v3-migration-guide.md b/docs/website/docs/user-guides/v3-migration-guide.md index 9cbf77fae7c..366889db43c 100644 --- a/docs/website/docs/user-guides/v3-migration-guide.md +++ b/docs/website/docs/user-guides/v3-migration-guide.md @@ -20,13 +20,43 @@ of the component from the cluster. If you have created an odo component using odo v2, this section will help you move it to use odo v3. 1. `cd` into the component directory, and delete the component from the Kubernetes cluster: ```shell - $ odo delete -f + odo delete ``` 2. Download and install odo v3 by following the steps mentioned [here](../overview/installation.md). 3. Use [`odo dev`](../command-reference/dev.md) to start developing your application using odo v3. +4. You can also use `odo list` to see a list of components that are running on the cluster and which version of odo + was used to create them. If you face any problem, [open an issue on odo's repository](https://github.com/redhat-developer/odo/issues/new?assignees=&labels=&template=Bug.md). +### What happened to Ingress/Route? +If you have used odo v2, you must have used Ingress (on Kubernetes) or Route (on OpenShift) to access the +application that was pushed to the cluster using `odo push`. odo v3 no longer creates an Ingress or a Route. Instead, +it uses port-forwarding. + +With v3, when you do `odo dev`, odo forwards a port on the development system to the port on the Kubernetes/OpenShift +cluster mapping to your running application. It also prints the information when the application has started on the +cluster. You would see a message like below: +```shell +$ odo dev +... +... +- Forwarding from 127.0.0.1:40001 -> 8080 +``` +This indicates that the port 40001 on the development system has been forwarded to port 8080 of the application +represented by the current odo component. + +:::info NOTE +odo no longer supports creation of Ingress/Route out of the box. Hence, `odo url` set of commands do not exist in v3. +::: + +### Changes to the way component debugging works +In odo v2, `odo push --debug` was used to run a component in debug mode. To setup port forwarding to the component's +debug port, you had to run `odo debug port-forward`. + +In odo v3, you need to specify the debug port in the `devfile.yaml` as an endpoint, and run `odo dev --debug` to +start the component in debug mode. + ### Commands added, modified or removed in v3 The following table contains a list of odo commands that have either been modified or removed. In case of a From 6c60a797381f7438e0b6300df3a87aebceabdfda Mon Sep 17 00:00:00 2001 From: Dharmit Shah Date: Fri, 9 Sep 2022 16:03:17 +0530 Subject: [PATCH 3/5] Second round of Armel's feedback Signed-off-by: Dharmit Shah --- .../docs/user-guides/v3-migration-guide.md | 43 ++++++++++++------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/website/docs/user-guides/v3-migration-guide.md b/docs/website/docs/user-guides/v3-migration-guide.md index 366889db43c..72d26e79095 100644 --- a/docs/website/docs/user-guides/v3-migration-guide.md +++ b/docs/website/docs/user-guides/v3-migration-guide.md @@ -3,6 +3,19 @@ title: Migrate from v2 to v3 sidebar_position: 2 --- +### Migrate existing odo component from v2 to v3 +If you have created an odo component using odo v2, this section will help you move it to use odo v3. +1. `cd` into the component directory, and delete the component from the Kubernetes cluster: + ```shell + odo delete + ``` +2. Download and install odo v3 by following the steps mentioned [here](../overview/installation.md). +3. Use [`odo dev`](../command-reference/dev.md) to start developing your application using odo v3. +4. You can also use `odo list` to see a list of components that are running on the cluster and which version of odo + was used to create them. + +If you face any problem, [open an issue on odo's repository](https://github.com/redhat-developer/odo/issues/new?assignees=&labels=&template=Bug.md). + ### Where are `odo push` and `odo watch` commands? `odo push` and `odo watch` have been replaced in v3 by a single command - `odo dev`. It does the job of two commands in a single command, and also allows the user to not watch if `--no-watch` flag is passed. @@ -16,19 +29,6 @@ long-running process that's going to block the terminal. Hitting `Ctrl+c` will s component from the cluster. In v2, you had to use `odo delete`/`odo component delete` to delete inner loop resources of the component from the cluster. -### Migrate existing odo component from v2 to v3 -If you have created an odo component using odo v2, this section will help you move it to use odo v3. -1. `cd` into the component directory, and delete the component from the Kubernetes cluster: - ```shell - odo delete - ``` -2. Download and install odo v3 by following the steps mentioned [here](../overview/installation.md). -3. Use [`odo dev`](../command-reference/dev.md) to start developing your application using odo v3. -4. You can also use `odo list` to see a list of components that are running on the cluster and which version of odo - was used to create them. - -If you face any problem, [open an issue on odo's repository](https://github.com/redhat-developer/odo/issues/new?assignees=&labels=&template=Bug.md). - ### What happened to Ingress/Route? If you have used odo v2, you must have used Ingress (on Kubernetes) or Route (on OpenShift) to access the application that was pushed to the cluster using `odo push`. odo v3 no longer creates an Ingress or a Route. Instead, @@ -55,7 +55,20 @@ In odo v2, `odo push --debug` was used to run a component in debug mode. To setu debug port, you had to run `odo debug port-forward`. In odo v3, you need to specify the debug port in the `devfile.yaml` as an endpoint, and run `odo dev --debug` to -start the component in debug mode. +start the component in debug mode. For example, a `container` component in the devfile should look like below, where +port 3000 is the application port and 5858 is the debug port: + +```yaml +- name: runtime + container: + image: registry.access.redhat.com/ubi8/nodejs-12:1-36 + memoryLimit: 1024Mi + endpoints: + - name: "3000-tcp" + targetPort: 3000 + - name: "5858-tcp" + targetPort: 5858 +``` ### Commands added, modified or removed in v3 @@ -79,7 +92,7 @@ modification, the modified command is mentioned in the `v3` column. Please refer | config unset | ❌ | | config view | ❌ | | debug info | ❌ (not needed as debug mode is start with odo dev --debug command that blocks terminal, the application can be running in inner-loop mode only if odo dev is running in terminal) | -| debug port-forward | ❌(port forwarding is automatic when users execute odo dev --debug) | +| debug port-forward | ❌ (port forwarding is automatic when users execute `odo dev --debug` as long as [the endpoint is defined in the devfile](#changes-to-the-way-component-debugging-works)) | | env set | ❌ | |env uset | ❌ | | env view | ❌ | From cc701fa4e281a381170de9e54654a34371dd54e8 Mon Sep 17 00:00:00 2001 From: Dharmit Shah Date: Wed, 14 Sep 2022 18:44:58 +0530 Subject: [PATCH 4/5] Address Armel and Charlie's feedback Signed-off-by: Dharmit Shah --- .../docs/user-guides/v3-migration-guide.md | 166 ++++++++++-------- 1 file changed, 90 insertions(+), 76 deletions(-) diff --git a/docs/website/docs/user-guides/v3-migration-guide.md b/docs/website/docs/user-guides/v3-migration-guide.md index 72d26e79095..87561432571 100644 --- a/docs/website/docs/user-guides/v3-migration-guide.md +++ b/docs/website/docs/user-guides/v3-migration-guide.md @@ -1,24 +1,26 @@ --- title: Migrate from v2 to v3 -sidebar_position: 2 +sidebar_position: 4 --- -### Migrate existing odo component from v2 to v3 -If you have created an odo component using odo v2, this section will help you move it to use odo v3. -1. `cd` into the component directory, and delete the component from the Kubernetes cluster: - ```shell - odo delete - ``` -2. Download and install odo v3 by following the steps mentioned [here](../overview/installation.md). -3. Use [`odo dev`](../command-reference/dev.md) to start developing your application using odo v3. -4. You can also use `odo list` to see a list of components that are running on the cluster and which version of odo - was used to create them. +### Migrate an existing `odo` component from v2 to v3 +If you have created an `odo` component using `odo` v2, this section will help you move it to use `odo` v3. +#### Step 1 +`cd` into the component directory, and delete the component from the Kubernetes cluster: +```shell +odo delete +``` +#### Step 2 +Download and [install odo v3](../overview/installation.md). -If you face any problem, [open an issue on odo's repository](https://github.com/redhat-developer/odo/issues/new?assignees=&labels=&template=Bug.md). +#### Step 3 +Run [`odo dev`](../command-reference/dev.md) to start developing your application using `odo` v3. + +#### Step 4 +Run `odo list` to see a list of components that are running on the cluster and what version of `odo` they are running. ### Where are `odo push` and `odo watch` commands? -`odo push` and `odo watch` have been replaced in v3 by a single command - `odo dev`. It does the job of two commands -in a single command, and also allows the user to not watch if `--no-watch` flag is passed. +`odo push` and `odo watch` have been replaced in v3 by a single command - `odo dev`. In v2, if you wanted to automatically sync the code on developer system with the application running on a Kubernetes cluster, you had to perform two steps - first `odo push` to start the application on the cluster, and second `odo watch` @@ -30,13 +32,13 @@ component from the cluster. In v2, you had to use `odo delete`/`odo component de of the component from the cluster. ### What happened to Ingress/Route? -If you have used odo v2, you must have used Ingress (on Kubernetes) or Route (on OpenShift) to access the -application that was pushed to the cluster using `odo push`. odo v3 no longer creates an Ingress or a Route. Instead, +If you have used `odo` v2, you must have used Ingress (on Kubernetes) or Route (on OpenShift) to access the +application that was pushed to the cluster using `odo push`. `odo` v3 no longer creates an Ingress or a Route. Instead, it uses port-forwarding. -With v3, when you do `odo dev`, odo forwards a port on the development system to the port on the Kubernetes/OpenShift -cluster mapping to your running application. It also prints the information when the application has started on the -cluster. You would see a message like below: +When running `odo dev`, `odo` forwards a port on the development system to the port on the container cluster allowing +you remote access to your deployed application. It also prints the information when the application has started on the +cluster: ```shell $ odo dev ... @@ -44,17 +46,18 @@ $ odo dev - Forwarding from 127.0.0.1:40001 -> 8080 ``` This indicates that the port 40001 on the development system has been forwarded to port 8080 of the application -represented by the current odo component. +represented by the current `odo` component. :::info NOTE -odo no longer supports creation of Ingress/Route out of the box. Hence, `odo url` set of commands do not exist in v3. +`odo` no longer supports creation of Ingress / Route out of the box. The `odo url` set of commands no longer exist +in v3. ::: ### Changes to the way component debugging works -In odo v2, `odo push --debug` was used to run a component in debug mode. To setup port forwarding to the component's +In `odo` v2, `odo push --debug` was used to run a component in debug mode. To setup port forwarding to the component's debug port, you had to run `odo debug port-forward`. -In odo v3, you need to specify the debug port in the `devfile.yaml` as an endpoint, and run `odo dev --debug` to +In `odo` v3, you need to specify the debug port in the `devfile.yaml` as an endpoint, and run `odo dev --debug` to start the component in debug mode. For example, a `container` component in the devfile should look like below, where port 3000 is the application port and 5858 is the debug port: @@ -69,63 +72,74 @@ port 3000 is the application port and 5858 is the debug port: - name: "5858-tcp" targetPort: 5858 ``` +### Changes to default configurations + +#### Ephemeral storage + +By default, `odo` v2 used [ephemeral storage](https://docs.openshift.com/container-platform/4.11/storage/understanding-ephemeral-storage.html) +for the components created using it. However, this has changed in `odo` v3, and it now uses the underlying storage +(Persistent Volumes) configured for use by the users. If you would like to continue using ephemeral storage for `odo` +components, you could change the configuration by doing: +```shell +odo preference set Ephemeral true +``` ### Commands added, modified or removed in v3 -The following table contains a list of odo commands that have either been modified or removed. In case of a +The following table contains a list of `odo` commands that have either been modified or removed. In case of a modification, the modified command is mentioned in the `v3` column. Please refer below legend beforehand: * 👷 currently not implemented, but might get implemented in future * ❌ not implemented, no plans for implementation -| v2 | v3 | -|--------------|--| -| app delete | ❌ | -| app describe | ❌ | -| app list | ❌ | -| catalog describe service| ❌ | -| catalog describe component | registry --details | -| catalog list service | 👷odo list services | -| catalog list component | registry | -| catalog search service | ❌ | -| catalog search component | registry --filter | -| config set | ❌ | -| config unset | ❌ | -| config view | ❌ | -| debug info | ❌ (not needed as debug mode is start with odo dev --debug command that blocks terminal, the application can be running in inner-loop mode only if odo dev is running in terminal) | -| debug port-forward | ❌ (port forwarding is automatic when users execute `odo dev --debug` as long as [the endpoint is defined in the devfile](#changes-to-the-way-component-debugging-works)) | -| env set | ❌ | -|env uset | ❌ | -| env view | ❌ | -|preference set| preference set| -|preference unset| preference unset| -|preference view| preference view| -|project create| create namespace| -|project delete| delete namespace| -|project get| ❌ | -|project list| list namespace| -|project set| set namespace| -|registry add| preference add registry| -|registry delete| preference remove registry| -|registry list| preference view | -| registry update|no command for update. If needed, it can be done using preference remove registry and preference add registry| -|service create/delete/describe/list|❌| -|storage create/delete/list|❌| -|test|👷(will be implemented after v3-GA) #6070| -|url create/delete/list| ❌ (odo dev automatically sets port forwarding between container and localhost. If users for some reason require Ingress or Route for inner-loop development they will have to explicitly define them in the devfile as kubernetes components)| -|build-images|build-images| -|deploy|deploy| -|login|login| -|logout|logout| -|create / component create|init| -|delete / component delete|delete component| -|describe / component describe|describe component| -|exec / component exec|❌| -|link / component link|add binding|list / component list| -|list|log / component log| -|logs|push / component push|in v3 there is only dev command that behaves more like watch in v2. There is an option to disable automatic reloads when a file is changed (--no-watch) in future there will be an option to trigger “sync” explicitly when --no-watch option is used)| -|status / component status|❌| -|unlink / component unlink|remove binding| -|watch / component watch|dev| -|❌|describe binding| -|❌|list binding| -|❌|analyze | \ No newline at end of file +| v2 | v3 | +| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| app delete | ❌ | +| app describe | ❌ | +| app list | ❌ | +| catalog describe service | ❌ | +| catalog describe component | registry --details | +| catalog list service | 👷odo list services | +| catalog list component | registry | +| catalog search service | ❌ | +| catalog search component | registry --filter | +| config set | ❌ | +| config unset | ❌ | +| config view | ❌ | | +| debug info | ❌ (not needed as debug mode is start with `odo dev --debug` command that blocks terminal, the application can be running in inner-loop mode only if `odo dev` is running in terminal) | +| debug port-forward | ❌ (port forwarding is automatic when users execute `odo dev --debug` as long as [the endpoint is defined in the devfile](#changes-to-the-way-component-debugging-works)) | +| env set | ❌ | +| env uset | ❌ | +| env view | ❌ | +| preference set | preference set | +| preference unset | preference unset | +| preference view | preference view | +| project create | create namespace | +| project delete | delete namespace | +| project get | ❌ | +| project list | list namespace | +| project set | set namespace | +| registry add | preference add registry | +| registry delete | preference remove registry | +| registry list | preference view | +| registry update | no command for update. If needed, it can be done using preference remove registry and preference add registry | +| service create/delete/describe/list | ❌ | +| storage create/delete/list | ❌ | +| test | 👷(will be implemented after v3-GA) #6070 | +| url create/delete/list | ❌ (`odo dev` automatically sets port forwarding between container and localhost. If users for some reason require Ingress or Route for inner-loop development they will have to explicitly define them in the devfile as kubernetes components) | +| build-images | build-images | | +| deploy | deploy | +| login | login | +| logout | logout | +| create / component create | init | +| delete / component delete | delete component | +| describe / component describe | describe component | +| exec / component exec | ❌ | +| link / component link | add binding | list / component list | +| list | log / component log | +| logs | push / component push | in v3 there is only dev command that behaves more like watch in v2. There is an option to disable automatic reloads when a file is changed (--no-watch) in future there will be an option to trigger “sync” explicitly when `--no-watch` option is used) | +| status / component status | ❌ | +| unlink / component unlink | remove binding | +| watch / component watch | dev | +| ❌ | describe binding | +| ❌ | list binding | +| ❌ | analyze | \ No newline at end of file From 2f1bc0970ec22149b08b948318f85786ba404560 Mon Sep 17 00:00:00 2001 From: Dharmit Shah Date: Thu, 15 Sep 2022 12:56:12 +0530 Subject: [PATCH 5/5] Name the endpoint and set exposure to none Signed-off-by: Dharmit Shah --- docs/website/docs/user-guides/v3-migration-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/website/docs/user-guides/v3-migration-guide.md b/docs/website/docs/user-guides/v3-migration-guide.md index 87561432571..2b1f969863e 100644 --- a/docs/website/docs/user-guides/v3-migration-guide.md +++ b/docs/website/docs/user-guides/v3-migration-guide.md @@ -69,7 +69,8 @@ port 3000 is the application port and 5858 is the debug port: endpoints: - name: "3000-tcp" targetPort: 3000 - - name: "5858-tcp" + - name: debug + exposure: none targetPort: 5858 ``` ### Changes to default configurations