The tunnel interface needs more networking examples

[ajzobro]

The tunnel interface explanation page doesn't have any examples of workshop configuration files demonstrating how the system plugs and slots are used.

workshop/docs/explanation/interfaces/tunnel-interface.rst

Line 32 in ea9b86d

Tunnel interface plug

Furthermore, given that our project can use a docker image in one setup, I was trying to set up the docker-ce sdk, but as I am running several applications in that environment with several ports in use, I want a way that I can take my (custom to my app under test) ports and make them available on the localhost.

I have yet to find any great examples in the documentation that show all the ways which slots and plugs can be used.

In one place I seemed to read that the slots or plugs (one of them) was defined by the sdk (does that mean that the publisher of the docker-ce sdk had to know my applications' ports and make them available in their SDK and I cannot add to the sdk definition?

Overall, since there are many magical things that slots and plugs and connections and the system interface can and cannot do, I would find it very helpful if there were more examples of a variety of scenarios. What I want to be able to do is all tcp networking.

[ajzobro]

Note, part 2 of the tutorial has this sentence "The slot we’re going to connect this plug to comes from the SDK itself and is named jupyter, so you don’t have to add it manually:" which makes it sound like it is possible to add arbitrary plugs/slots to arbitary SDKs.

In my case (canonical/testflinger#1144), I need to add them manually as the run-of-the-mill docker-ce SDK doesn't offer ip/port slots for all my applications by default (and I can't see how it could be that docker as an SDK could capture all of the possible ports that someone developing with docker might use). This is almost no different than the cases of running any arbitrary service in the workshop and exporting its network to the localhost.

I can also see no way to map a port from inside the LXD container to not just the host, but external to the host. E.g. I was trying to use the ollama SDK in a single workshop, but then share that LLM with other workshops and even other computers to no avail. I am now turning to hosting it myself in an LXD container.

[jonathan-conder]

The tunnel interface explanation page doesn't have any examples of workshop configuration files demonstrating how the system plugs and slots are used.

Some examples can be found in the how-to guide.

In one place I seemed to read that the slots or plugs (one of them) was defined by the sdk (does that mean that the publisher of the docker-ce sdk had to know my applications' ports and make them available in their SDK and I cannot add to the sdk definition?

You can extend the SDK's built-in plugs and slots for a particular workshop via the workshop definition file. The how-to guide I linked above has some examples of this.

I would not modify the docker-ce SDK itself, but you can create an SDK for your specific application and put the plugs or slots in there if you prefer. It depends whether you think other workshops might use the same plugs and slots, or if they are specific to a single workshop.

Note, part 2 of the tutorial has this sentence "The slot we’re going to connect this plug to comes from the SDK itself and is named jupyter, so you don’t have to add it manually:" which makes it sound like it is possible to add arbitrary plugs/slots to arbitary SDKs.

It's not arbitrary, we have security policies that prevent certain scenarios. But for tunnels pretty much anything goes, yes. In this case the jupyter SDK has a built-in slot, so you don't need to add one as part of the workshop definition.

I can also see no way to map a port from inside the LXD container to not just the host, but external to the host. E.g. I was trying to use the ollama SDK in a single workshop, but then share that LLM with other workshops and even other computers to no avail. I am now turning to hosting it myself in an LXD container.

For this, you would create a tunnel from the host into the ollama workshop. After that, from a networking standpoint it will look like ollama is running on the host. If a workshop wants to talk to it, you can create another tunnel going the other direction.

[ajzobro]

Thanks for the reply, I appreciate you taking the time to support responding to this request. Seeing different variations of the use of certain key concepts like the tunnels is very helpful.

1. Examples

I'm going to propose more internal linking in the documentation, I will PR it if no one beats me to it and perhaps add more examples if I can get to the point of understanding the nuances of these concepts on my own. These two examples were indeed what I could not find when looking in the references and explanations about the syntax for tunnels: https://ubuntu.com/workshop/docs/how-to/customize-workshops/forward-ports/#share-host-services https://ubuntu.com/workshop/docs/how-to/customize-workshops/forward-ports/#expose-workshop-services and I think that the explanation and reference sections should also refer to them.

2. Routing to external clients

Take for example the case of the ollama SDK once more: I have been successful in exposing it to localhost:11434 but not 0.0.0.0:11434 -- the implication of which is that only the host, and not members of my LAN can access the service. This is why I believe that the only solution I have is to self-host ollama to make it available to my LAN. This is one area where I would like confirmation that I have indeed hit a limitation of the plugs/slots tunnel mechanism, as I believe this may be intentional and is indeed why I cannot use workshops' ollama SDK for my purposes and instead I need to host my own ollama service to make my local LLM available to my LAN.

If I am wrong, then, please help me understand what the syntax would be to expose the service to my LAN (not my localhost).

flowchart LR
  client[External PC<br/>Client: :8080] -->|connects to host port :8080| hostPort

  subgraph host[Host]
    direction LR
    hostPort[Host port<br/>0.0.0.0:8080]

    subgraph container[Container]
      direction LR
      containerPort[Container port<br/>:80]
      app[App/service]
      containerPort --> app
    end

    hostPort -->|published/mapped| containerPort
  end

Loading

[jonathan-conder]

I'm going to propose more internal linking in the documentation

Let's run this past @akcano

Take for example the case of the ollama SDK once more: I have been successful in exposing it to localhost:11434 but not 0.0.0.0:11434

If you put 0.0.0.0:11434 in a system SDK plug, it should work, but it may require manual connection. Use workshop connections --all to see if it's connected or not.

Once connected, other machines on your LAN can then connect to the IP address of the machine running the workshop. If not, you may need to open a port in that machine's firewall.

[akcano]

@ajzobro thanks for raising this; I'll be happy to look at the PR. Please mind that we (mostly) confine cross-pillar references (e.g. howto -> explanation or reference -> how-to) to 'See also' sections to avoid navigation loops. Meanwhile, I will think how we can expose this better by other means.

[shizuku198411]

Hi, @ajzobro

I initially ran into a similar issue, but it looks like the current design requires manually connecting the tunnel in order to access it from an external host.

My understanding is that this is intentional from Workshop’s design perspective. Workshop seems to be focused on providing an isolated local development environment, rather than something like Docker where applications are expected to run for a long time and be exposed externally by default. So I think this behavior is likely intended for better security.

The documentation also says:

https://ubuntu.com/workshop/docs/explanation/interfaces/tunnel-interface/#connection

The interface is connected automatically at launch or refresh, provided that:
        :
- The plug listens on localhost or a Unix domain socket

Here is a brief example of how the tunnel interface can be used to access a service from an external host.

workshop.yaml

name: dev-test
base: ubuntu@24.04
sdks:
  - name: ollama
    channel: cuda/stable
  - name: system
    plugs:
      public-tunnel:
        interface: tunnel
        endpoint: 0.0.0.0:1234

I intentionally used public-tunnel as the plug name instead of ollama. This is to avoid giving the impression that the plug name must match the SDK name, or that users need to know the internal SDK structure.

verify connections

After launching the workshop, you can check the list of connections with workshop connections --all.

$ workshop connections --all
INTERFACE  PLUG                           SLOT                           NOTES
mount      dev-test/ollama:models         dev-test/system:mount          -
tunnel     -                              dev-test/ollama:ollama-server  -
tunnel     dev-test/system:public-tunnel  -

As shown above, the tunnel on the SDK side (SLOT) and the tunnel on the host side (PLUG) are created but not connected automatically.

connect

You can connect them manually with workshop connect.

$ workshop connect dev-test/system:public-tunnel dev-test/ollama:ollama-server

$ workshop connections --all
INTERFACE  PLUG                           SLOT                           NOTES
mount      dev-test/ollama:models         dev-test/system:mount          -
tunnel     dev-test/system:public-tunnel  dev-test/ollama:ollama-server  manual

Now the SDK-side tunnel and the host-side tunnel are connected.

$ workshop info
name:     dev-test
base:     ubuntu@24.04
project:  ~/tmp/test
status:   ready
notes:    –
sdks:
  system:
    installed:  (2)
    tunnels:
      public-tunnel:
        from:  0.0.0.0:1234/tcp
        to:    127.0.0.1:11434/tcp

You can also confirm from workshop info that the tunnel forwards host port 1234/tcp to 11434/tcp on the SDK side.
With this setup, you should be able to access the Ollama from an external host through :1234.
Could you try the above and see if it works for your case?

And also you can also create a project-local SDK that defines its own slot. It does not need to be published to the SDK store.

https://github.com/shizuku198411/Rk-C/tree/main/.workshop/rkc-base

This is a custom SDK that I use in one of my own projects. It defines a slot that exposes port 1234 for GDB connections.
If you are interested in customizing SDKs, it might be useful as a reference.

[ajzobro]

@jonathan-conder

$ cat workshop.yaml 
name: ollama
base: ubuntu@24.04

sdks:
  - name: ollama
    channel: cuda/stable
  - name: system
    plugs:
      ollama-server:
        interface: tunnel
        #endpoint: 11434                    # only localhost
        #endpoint: localhost:11434          # only localhost
        endpoint: 0.0.0.0:11434             # does not work

        # TODO: check for auth params for ollama sdk
$ workshop connections
INTERFACE  PLUG                  SLOT                 NOTES
gpu        ollama/ollama:gpu     ollama/system:gpu    -
mount      ollama/ollama:models  ollama/system:mount  -
$ workshop connections --all
INTERFACE  PLUG                         SLOT                         NOTES
gpu        ollama/ollama:gpu            ollama/system:gpu            -
mount      ollama/ollama:models         ollama/system:mount          -
tunnel     -                            ollama/ollama:ollama-server  -
tunnel     ollama/system:ollama-server  -                            -
> workshop connect ollama/system:ollama-server ollama/ollama:ollama-server 
> workshop connections --all
INTERFACE  PLUG                         SLOT                         NOTES
gpu        ollama/ollama:gpu            ollama/system:gpu            -
mount      ollama/ollama:models         ollama/system:mount          -
tunnel     ollama/system:ollama-server  ollama/ollama:ollama-server  manual

Indeed, the manual connection did the trick. Thank you.

Final answer, using just:

$ cat justfile 
# Start ollama in a workshop and share with the world
# Warning: no auth!

run:
    # we have to stop first to have a known state; workshop stop will not error if already stopped, but workshop start will throw if already started.
    workshop stop ollama
    workshop start ollama
    workshop connect ollama/system:ollama-server ollama/ollama:ollama-server
    workshop connections
$ just run
# we have to stop first to have a known state; workshop stop will not error if already stopped, but workshop start will throw if already started.
workshop stop ollama
"ollama" stopped
workshop start ollama
"ollama" started
workshop connect ollama/system:ollama-server ollama/ollama:ollama-server
workshop connections
INTERFACE  PLUG                         SLOT                         NOTES
gpu        ollama/ollama:gpu            ollama/system:gpu            -
mount      ollama/ollama:models         ollama/system:mount          -
tunnel     ollama/system:ollama-server  ollama/ollama:ollama-server  manual

[jonathan-conder]

Nice!

we have to stop first to have a known state; workshop stop will not error if already stopped, but workshop start will throw if already started.

We should probably do something about this