Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add hybrid mode content #450

Closed
wants to merge 6 commits into from
Closed

Add hybrid mode content #450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4bae84e
Add hybrid mode content
Jul 17, 2023
7e5dd13
move table to manifest reference: mode
Jul 17, 2023
d45fc31
Add compatible commands per mode
Jul 20, 2023
d6644af
Update src/content/reference/manifest.mdx
Jul 27, 2023
e1b7af4
Update src/content/reference/cli.mdx
Jul 27, 2023
fddf73c
Update src/content/cloud/okteto-cli.mdx
Jul 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions src/content/cloud/okteto-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ sidebar_label: Okteto CLI
id: okteto-cli
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

[Dev Environments](reference/development-environments.mdx) allow you to develop your deployed application locally. You continue coding in your favorite IDE and see the changes live on the deployed version of your application as soon as you hit save.
Okteto CLI is an [open source](https://github.com/okteto/okteto) client-side only tool that allows you to launch Dev Environments in any Kubernetes cluster: your own, [Okteto Cloud](index.md), or [Okteto Self-Hosted](self-hosted.mdx).

Expand All @@ -17,6 +20,97 @@ Learn more about the Okteto CLI
- [FAQs](reference/faqs.mdx)
- [Known Issues](reference/known-issues.mdx)

## okteto up

The `okteto up` command is one of Okteto CLI's main features and key to the Okteto development experience. This command uses the [Okteto Manifest](/reference/manifest) you define to build, deploy, and synchronize your local files with the remote development container.

This command has two modes: `sync` (default mode) and `hybrid` which are detailed below.

| | `sync` (default) | `hybrid` |
| :---------------- | :--------------- | :------- |
| Source code | Source code is edited locally and synchronizes bidirectionally (via Syncthing) with a copy of the source code in the remote development container. | Source code is edited locally for a chosen set of microservices. |
| App location | The application exists entirely within the remote development container. | Your application is split between your local environment and the remote development container based on your configuration. |
| `command` context | CLI commands run in the remote development container. | CLI commands run on your local machine, so traffic need to be rerouted to/from the cluster, e.g. using the reverse option |

Below is a reference to help you configure your [`dev` section](/reference/manifest/#dev-object-optional) based on the mode you select. **Standard** configuration options work in both modes and **Sync** options work *only* when `sync` is selected.

For example, if you select `hybrid` mode, you can only use the configuration options in your manifest `dev` section listed under **Standard**. Any configuration options in the **Sync** list will *not work*.

<details>
<summary>Configuration reference: dev section</summary>
<Tabs>
<TabItem value="Standard" label="Standard" default>
<ul>
<li>annotations</li>
<li>autocreate</li>
<li>command</li>
<li>container</li>
<li>envFiles</li>
<li>environment</li>
<li>environment</li>
<li>forward</li>
<li>metadata</li>
<li>mode</li>
<li>reverse</li>
<li>selector</li>
<li>workdir</li>
</ul>
</TabItem>
<TabItem value="Sync" label="Sync">
<ul>
<li>affinity</li>
<li>context</li>
<li>externalVolumes</li>
<li>image</li>
<li>imagePullPolicy</li>
<li>initContainer</li>
<li>initFromImage</li>
<li>lifecycle</li>
<li>namespace</li>
<li>nodeSelector</li>
<li>persistentVolume</li>
<li>push</li>
<li>replicas</li>
<li>secrets</li>
<li>securityContext</li>
<li>serviceAccount</li>
<li>sshServerPort</li>
<li>sync</li>
<li>tolerations</li>
<li>volumes</li>
</ul>
</TabItem>
</Tabs>
</details>

### When to use `hybrid` development mode

A typical use case for using `hybrid` development mode is when the filesync or rebuild is significantly slower on the remote dev container, such as when using Webpack where this becomes very noticeable compared to your local environment.

Another use case is when you’re using a framework that is IDE-heavy. For example, on Java/Spring, IDEs tend to be pre-configured to run tests, start services, and connect debuggers. You lose some of that ‘click and you are done’ when you are using the traditional `okteto up` and the default `sync` mode.

:::info
Keep in mind that using `hybrid` mode means breaking replicability between Operating Systems (local and remote) and may add latency when accessing other services in the cluster.
:::

### How to use `hybrid` development mode

In order to use `hybrid` mode you only need to configure the necessary ports to expose the service running on your local machine to the remote development container. This enables other components running on the cluster to communicate with your local service(s) as if your local service(s) was running in the cluster as well.

To do this, you can use the [reverse](/reference/manifest/#reverse-string-optional) field to expose the desired port of your local machine to the desired port on the remote development container.

```yaml
dev:
frontend:
mode: hybrid
reverse:
- 3000:8080
workdir: ./frontend
command: ["npx webpack watch --mode development"]

```

In the example above we have indicated that we are developing the `frontend` service locally using the `mode: hybrid` field. The service running locally will execute the `command` instructions in the directory indicated in `workdir`. Additionally, the application will expose port `8080` on the local machine and communicate bidirectionally with port `3000` on the development container. This makes it possible for other components running on the cluster to access the local service as if it were running remotely.

## Deployment Manifests

Expand Down
12 changes: 8 additions & 4 deletions src/content/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -709,8 +709,9 @@ The `status` command should be run from the same location than `okteto up`.

### up

Activate a development container.
If needed, `okteto up` builds the images and runs the deploy commands defined in your [Okteto Manifest](reference/manifest.mdx).
The `okteto up` command is one of Okteto’s key features. This command uses the [Okteto Manifest](/reference/manifest) you define to build, deploy, and synchronize your local files with the remote development container.

This command has two modes: `sync` (default mode) and `hybrid` which are detailed in the manifest reference: [mode](/reference/manifest/#mode-string-optional).

```console
$ okteto up [devName]
Expand All @@ -723,8 +724,11 @@ When you run `okteto up`, okteto scales to zero the specified deployment and cre
- Automatic local and remote port forwarding using [SSH](reference/ssh-server.mdx). This allows you to do things like access your cluster services via `localhost` or connect a remote debugger.
- A watcher service to keep the definition of the mirror deployment up to date with original deployment.

It's worth noting that your development deployment inherits the original deployment manifest definition.
Therefore, the development deployment uses the same service account, environment variables, secrets, volumes, sidecars, ... than the original deployment, providing a fully integrated development environment.
:::info
Note: The bidirectional file sync does not apply if using `hybrid` mode.
:::

It's worth noting that your development deployment inherits the original deployment manifest definition. Therefore, the development deployment uses the same service account, environment variables, secrets, volumes, sidecars, ... as the original deployment, providing a fully integrated development environment.

> Run [`okteto down`](#down) to restore your original deployment.

Expand Down
25 changes: 25 additions & 0 deletions src/content/reference/manifest.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -509,6 +509,31 @@ metadata:
custom.label/dev: "true"
```

#### mode (string, optional)

Defines how `okteto up` will setup the development container and behave within the cluster.

Currently two options are available:

- `sync`: (default) Sync & run your code in a remote development container.
- `hybrid`: Run your code on your local computer instead of in a remote development container, while rest of your service components runs in your remote cluster.

| | `sync` (default) | `hybrid` |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we have the same table in cloud/okteto-cli. Should we link that table here instead of repeating it?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My vote would be to repeat it because I think it's important in both sections and is succinct.

If the content was more verbose then I'd say link to it, but since this is fairly concise I think it's worth saving the user a trip to another doc page so they can stay in the same context.

Happy to hear contrary opinion though 😄

| :---------------- | :--------------- | :------- |
| Source code | Source code is edited locally and synchronizes bidirectionally (via Syncthing) with a copy of the source code in the remote development container. | Source code is edited locally for a chosen set of microservices. |
| App location | The application exists entirely within the remote development container. | Your application is split between your local environment and the remote development container based on your configuration. |
| `command` context | CLI commands run in the remote development container. | CLI commands run on your local machine, so traffic need to be rerouted to/from the cluster, e.g. using the reverse option |

```yaml
dev:
frontend:
mode: hybrid
reverse:
- 3000:8080
workdir: ./frontend
command: ["npx webpack watch --mode development"]
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the new hybrid not all parameters in the dev section apply in this mode. Shouldn't we add a clarification in every one of these parameters stating if it's supported in sync and/or hybrid mode?

Example:

### envFiles
> Supported in both `sync` and `hybrid` modes.
...

### affinity
> Only supported in `sync` mode.
...

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rlamana Ah yes. I think that's a good and important clarification to add.

Are those the only two exceptions or do we need to compile a complete list?

Copy link
Contributor

@rlamana rlamana Jul 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, we have to take into account all of them. The list is compiled in the spec doc here: https://www.notion.so/okteto/Okteto-CLI-3-0-7fbd3a6a566145d3a4930d3c15fc642d?pvs=4#37aeeb1c05824203ac5f8132caf76e1f

And also the work done here: okteto/okteto#3808

@andreafalzetti @teresaromero you might have more context if that table there is updated after the work done there or is there anything we need to change?

Copy link
Contributor

@andreafalzetti andreafalzetti Jul 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@omnomagonz @rlamana the following might require a bit of polishing but should include almost everything:

These are the fields that are supported in sync but not in hybrid:

  • affinity
  • context
  • externalVolumes
  • image
  • imagePullPolicy
  • initContainer
  • initFromImage
  • lifecycle
  • namespace
  • nodeSelector
  • persistentVolume
  • push
  • replicas
  • secrets
  • securityContext
  • serviceAccount
  • sshServerPort
  • sync
  • tolerations
  • volumes

These fields work in both modes:

  • annotations
  • autocreate
  • command
  • container
  • envFiles
  • environment
  • environment
  • forward
  • metadata
  • mode
  • reverse
  • selector
  • workdir

These fields work in sync but we're not sure if they make sense for hybrid:

  • interface
  • probes
  • remote
  • timeout

This field exists in code but not documented and not sure if it should be supported:

  • args

Should work in both but deprecated:

  • healthchecks
  • labels

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot @andreafalzetti for the updated list. We will need to clarify those that we are not sure:

  • interface
  • probes
  • remote
  • timeout
    As discussed offline maybe @pchico83 can help us with more context on these, and soon before he leaves on PTO.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolving this conversation; please see latest commit: d45fc31 and add additional comments :)

I left out some of the nuanced details like "deprecated but works in both" and "exists in code but not documented". We can iterate to add more clarity on these but I didn't want to get blocked on nuance for now

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@omnomagonz "not sure if they make sense for hybrid" meant that we are still deciding if the will fall under the "ignored/unsupported" fields or if we will implement it in both modes. But there will be a final resolution for all those so that the final list will only have "supported or not supported" for each mode.

@andreafalzetti what is the current status of those fields?

Copy link
Contributor

@rlamana rlamana Jul 28, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion, besides adding a table I will still add a "hint" on every single parameter. It is common to just go and check a parameter in the docs to learn about it. If the user doesn't have that info there (and assuming they are aware of these two modes and know there is a table for it), users will have to go to look for the table and see if the parameter is there, and then maybe go back to the parameter description to continue reading about it. I find the table less important since you usually go seeking for documentation on a particular item. It is pretty common to see this type of support descriptions in docs of this kind.

Copy link
Contributor

@andreafalzetti andreafalzetti Aug 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rlamana for remote I was able to verify that it works for hybrid too. timeout for me doesn't work in sync either, so I've created okteto/okteto#3849

these two work:

  • interface
  • probes

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@andreafalzetti So after our daily today, I think probes was clarified and it's good to go. What about interface then?

#### nodeSelector (map[string]string, optional)

List of labels that the node must have to include the development container on it.
Expand Down