@exagone313/dsh-podman 1.0.4 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +1 -0
  2. package/README.zh.md +1 -0
  3. package/dist/approval-reasons.d.ts +12 -0
  4. package/dist/approval-reasons.js +15 -0
  5. package/dist/approval.js +21 -0
  6. package/dist/card-route.js +83 -1
  7. package/dist/client/ContainerCard.js +14 -2
  8. package/dist/client/card-protocol.d.ts +16 -1
  9. package/dist/client/container-card-controller.d.ts +8 -2
  10. package/dist/client/container-card-controller.js +21 -0
  11. package/dist/client/container-card-ports.d.ts +13 -0
  12. package/dist/client/container-card-ports.js +74 -0
  13. package/dist/client/container-card-row.d.ts +3 -0
  14. package/dist/client/container-card-row.js +12 -2
  15. package/dist/client/container-card-workspace.d.ts +3 -0
  16. package/dist/client/container-card-workspace.js +2 -2
  17. package/dist/client/index.js +653 -386
  18. package/dist/client/locales.d.ts +1 -1
  19. package/dist/client/locales.js +30 -0
  20. package/dist/client/tool-presentations.d.ts +167 -0
  21. package/dist/client/tool-presentations.js +167 -0
  22. package/dist/client/tool-views.d.ts +1 -2
  23. package/dist/client/tool-views.js +54 -190
  24. package/dist/generated/version.d.ts +2 -2
  25. package/dist/generated/version.js +2 -2
  26. package/dist/grpc/proto/dshctl/v1/control.proto +47 -1
  27. package/dist/grpc/proto/dshgateway/v1/gateway.proto +89 -0
  28. package/dist/grpc/proto/dshguest/v1/guest.proto +17 -0
  29. package/dist/index.d.ts +3 -2
  30. package/dist/index.js +3 -2
  31. package/dist/public.d.ts +1 -0
  32. package/dist/public.js +14 -0
  33. package/dist/publish-port.d.ts +6 -0
  34. package/dist/publish-port.js +37 -0
  35. package/dist/tool-defs.js +15 -1
  36. package/dist/tool-handlers.js +31 -1
  37. package/dist/tool-params.d.ts +48 -0
  38. package/dist/tool-params.js +42 -0
  39. package/docs/architecture.md +44 -7
  40. package/docs/architecture.zh.md +38 -6
  41. package/docs/configuration.md +25 -0
  42. package/docs/configuration.zh.md +23 -0
  43. package/docs/development.md +9 -2
  44. package/docs/development.zh.md +9 -2
  45. package/docs/install-dsh-and-dsh-podman.md +10 -4
  46. package/docs/install-dsh-and-dsh-podman.zh.md +9 -3
  47. package/docs/uninstall.md +4 -3
  48. package/docs/uninstall.zh.md +3 -2
  49. package/docs/update.md +23 -6
  50. package/docs/update.zh.md +23 -6
  51. package/docs/usage.md +48 -13
  52. package/docs/usage.zh.md +31 -2
  53. package/package.json +1 -1
  54. package/quadlet/dsh-podman-gateway.container +23 -0
  55. package/quadlet/dsh-podman-orchestrator.container +1 -1
  56. package/quadlet/dsh.container +1 -1
@@ -4,7 +4,8 @@
4
4
  import { bytesText, currentCwd, fsError, guestCwd, outputLines, resolveToolBinding, runExec, sessionWorkspaceSlug, streamLines, unaryGuest, } from "./guest-rpc.js";
5
5
  import { inferMountKind, mountsFromInput, projectMountDestinationReason, } from "./mount-input.js";
6
6
  import { mergeDefaultEnv } from "./container-env.js";
7
- import { publicContainer, publicDaemon, publicImage, publicMount, } from "./public.js";
7
+ import { publicContainer, publicDaemon, publicImage, publicMount, publicPublishedPort, } from "./public.js";
8
+ import { portProtocolToProto } from "./publish-port.js";
8
9
  import { grpc } from "./grpc/runtime-client.js";
9
10
  import { defaultMountMode, mountKindToProto, mountModeToProto, } from "./mount-enums.js";
10
11
  import { containerNotFound, } from "./workspace-binding.js";
@@ -403,6 +404,35 @@ export const toolHandlers = {
403
404
  const row = await resolver.control("updateContainerMount", request);
404
405
  return publicContainer(row);
405
406
  },
407
+ container_publish_port: async (resolver, input, exec) => {
408
+ const request = {
409
+ workspaceSlug: await sessionWorkspaceSlug(resolver, currentCwd(exec)),
410
+ container: input.container,
411
+ port: input.port,
412
+ protocol: portProtocolToProto(input.protocol),
413
+ };
414
+ // An omitted suggestion asks the gateway to choose a free host port.
415
+ if (input.suggestedHostPort !== undefined) {
416
+ request.suggestedHostPort = input.suggestedHostPort;
417
+ }
418
+ const published = await resolver.control("publishPort", request);
419
+ return { container: input.container, ...publicPublishedPort(published) };
420
+ },
421
+ container_unpublish_port: async (resolver, input, exec) => {
422
+ const request = {
423
+ workspaceSlug: await sessionWorkspaceSlug(resolver, currentCwd(exec)),
424
+ container: input.container,
425
+ port: input.port,
426
+ protocol: portProtocolToProto(input.protocol),
427
+ };
428
+ await resolver.control("unpublishPort", request);
429
+ return {
430
+ container: input.container,
431
+ port: input.port,
432
+ protocol: input.protocol ?? "tcp",
433
+ unpublished: true,
434
+ };
435
+ },
406
436
  container_path_set: async (resolver, input, exec) => {
407
437
  const sessionCwd = currentCwd(exec);
408
438
  const slug = await sessionWorkspaceSlug(resolver, sessionCwd);
@@ -326,6 +326,54 @@ export declare const containerMountUpdateParameters: {
326
326
  };
327
327
  required: string[];
328
328
  };
329
+ export declare const containerPublishPortParameters: {
330
+ type: string;
331
+ properties: {
332
+ container: {
333
+ type: string;
334
+ description: string;
335
+ };
336
+ port: {
337
+ type: string;
338
+ minimum: number;
339
+ maximum: number;
340
+ description: string;
341
+ };
342
+ protocol: {
343
+ type: string;
344
+ enum: string[];
345
+ description: string;
346
+ };
347
+ suggestedHostPort: {
348
+ type: string;
349
+ minimum: number;
350
+ maximum: number;
351
+ description: string;
352
+ };
353
+ };
354
+ required: string[];
355
+ };
356
+ export declare const containerUnpublishPortParameters: {
357
+ type: string;
358
+ properties: {
359
+ container: {
360
+ type: string;
361
+ description: string;
362
+ };
363
+ port: {
364
+ type: string;
365
+ minimum: number;
366
+ maximum: number;
367
+ description: string;
368
+ };
369
+ protocol: {
370
+ type: string;
371
+ enum: string[];
372
+ description: string;
373
+ };
374
+ };
375
+ required: string[];
376
+ };
329
377
  export declare const containerPathSetParameters: {
330
378
  type: string;
331
379
  properties: {
@@ -238,6 +238,48 @@ export const containerMountUpdateParameters = {
238
238
  },
239
239
  required: ["container", "mode"],
240
240
  };
241
+ export const containerPublishPortParameters = {
242
+ type: "object",
243
+ properties: {
244
+ container: containerParam,
245
+ port: {
246
+ type: "integer",
247
+ minimum: 1,
248
+ maximum: 65535,
249
+ description: "TCP port the service listens on inside the pod's network namespace.",
250
+ },
251
+ protocol: {
252
+ type: "string",
253
+ enum: ["tcp"],
254
+ description: "Transport to publish. Only tcp is supported for now; udp and http are reserved for later.",
255
+ },
256
+ suggestedHostPort: {
257
+ type: "integer",
258
+ minimum: 1024,
259
+ maximum: 65535,
260
+ description: "Host port to prefer, between 1024 and 65535. Omit to let the gateway choose a free one.",
261
+ },
262
+ },
263
+ required: ["container", "port"],
264
+ };
265
+ export const containerUnpublishPortParameters = {
266
+ type: "object",
267
+ properties: {
268
+ container: containerParam,
269
+ port: {
270
+ type: "integer",
271
+ minimum: 1,
272
+ maximum: 65535,
273
+ description: "Pod port whose host exposure is removed.",
274
+ },
275
+ protocol: {
276
+ type: "string",
277
+ enum: ["tcp"],
278
+ description: "Transport to unpublish. Only tcp is supported for now.",
279
+ },
280
+ },
281
+ required: ["container", "port"],
282
+ };
241
283
  export const containerPathSetParameters = {
242
284
  type: "object",
243
285
  properties: {
@@ -6,13 +6,14 @@ SPDX-License-Identifier: MIT
6
6
 
7
7
  # Architecture
8
8
 
9
- dsh-podman has three components:
9
+ dsh-podman has four components:
10
10
 
11
- | Component | Runs | What it does |
12
- | ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
13
- | `@exagone313/dsh-podman` | Inside dsh itself | Registers `ctx.subprocess` and `ctx.fs` backed by the orchestrator |
14
- | `dsh-podman-guest-agent` | Inside every guest container | Serves the exec/filesystem gRPC API for one workspace |
15
- | `dsh-podman-orchestrator` | A container with access to the Podman API | Owns the control socket and persisted state; creates/removes guest containers; builds workspace images |
11
+ | Component | Runs | What it does |
12
+ | ------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
13
+ | `@exagone313/dsh-podman` | Inside dsh itself | Registers `ctx.subprocess` and `ctx.fs` backed by the orchestrator |
14
+ | `dsh-podman-guest-agent` | Inside every guest container | Serves the exec/filesystem gRPC API for one workspace |
15
+ | `dsh-podman-orchestrator` | A container with access to the Podman API | Owns the control socket and persisted state; creates/removes guest containers; builds workspace images |
16
+ | `dsh-podman-gateway` | A container on the host network, shipped by the standard install | Bridges a published pod port to the host loopback |
16
17
 
17
18
  The plugin auto-creates a missing workspace using its configured default image
18
19
  and a single read-write project mount; `container_mount_update` can remount that
@@ -52,7 +53,8 @@ workspace's current image), `RemoveContainer`, `AddContainerMount`,
52
53
  `AddContainerSecret`, and `RemoveContainerSecret`. The service also exposes the
53
54
  workspace, volume, secret, image (build, rebuild, remove and base-image pull),
54
55
  and cache (list and clean) operations that back the Podman page, plus
55
- `GetVersion`.
56
+ `GetVersion`, `GetGatewayStatus`, and `PublishPort` / `UnpublishPort` /
57
+ `ListPublishedPorts` for [published ports](#published-ports).
56
58
 
57
59
  ## Workspaces and pods
58
60
 
@@ -164,6 +166,41 @@ Recreating a container or shutting down the orchestrator first asks the
164
166
  container's guest agent to gracefully stop its daemons (SIGTERM, ~10s grace)
165
167
  before podman tears the container down.
166
168
 
169
+ ## Published ports
170
+
171
+ A daemon listening inside a pod is not reachable from the host: each pod has its
172
+ own network namespace and nothing publishes ports. `container_publish_port`
173
+ brings one TCP port out, through two forwards:
174
+
175
+ ```
176
+ client -> <address>:<port> -> gateway -> unix socket (socket root) -> guest agent -> 127.0.0.1:<pod port>
177
+ ```
178
+
179
+ The **guest agent** listens on a short, deterministic Unix socket inside the
180
+ container's own socket directory — the one shared with the orchestrator and the
181
+ plugin, where its own `guest.sock` lives — and forwards each connection to
182
+ `127.0.0.1:<port>` inside the pod. The **gateway** — a container the standard
183
+ install ships, on the host network — mounts the same socket root, binds
184
+ `127.0.0.1:<host port>` and forwards to that socket. It returns the address
185
+ alongside the port, so the tool can answer `tcp://127.0.0.1:6666`; the address
186
+ belongs to the gateway, which is what would let a later HTTP publish answer a
187
+ hostname instead.
188
+
189
+ The **orchestrator** owns the lifecycle. It records every published port on the
190
+ container, re-creates the guest socket after a container recreate (the gateway
191
+ binding survives, so the host port does not move) and releases the binding when
192
+ the port is unpublished, the container is removed, or its workspace is torn
193
+ down. No published port lives only in the gateway: it holds bindings only while
194
+ the orchestrator keeps a lease stream open, so an orchestrator that stops or
195
+ crashes cannot leave a host port behind, and a gateway that restarts is re-bound
196
+ from the store.
197
+
198
+ Only TCP is implemented. The wire format, the stored record and the returned
199
+ address string already carry a protocol, so a later UDP or HTTP publish does not
200
+ have to change them. The gateway is optional: only publishing needs it, and
201
+ without it that tool reports it is not running while every other feature is
202
+ unaffected.
203
+
167
204
  ## Images
168
205
 
169
206
  The orchestrator builds workspace images through Podman (see
@@ -6,13 +6,14 @@ SPDX-License-Identifier: MIT
6
6
 
7
7
  # 架构
8
8
 
9
- dsh-podman 由三个组件组成:
9
+ dsh-podman 由四个组件组成:
10
10
 
11
- | 组件 | 运行位置 | 功能 |
12
- | ------------------------- | ---------------------------- | ---------------------------------------------------------------------- |
13
- | `@exagone313/dsh-podman` | dsh 内部 | 注册由 orchestrator 提供支撑的 `ctx.subprocess` 和 `ctx.fs` |
14
- | `dsh-podman-guest-agent` | 每个 guest 容器内部 | 为一个工作区提供 exec/filesystem gRPC API |
15
- | `dsh-podman-orchestrator` | 一个可访问 Podman API 的容器 | 持有 control socket 和持久化状态;创建/删除 guest 容器;构建工作区镜像 |
11
+ | 组件 | 运行位置 | 功能 |
12
+ | ------------------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
13
+ | `@exagone313/dsh-podman` | dsh 内部 | 注册由 orchestrator 提供支撑的 `ctx.subprocess` 和 `ctx.fs` |
14
+ | `dsh-podman-guest-agent` | 每个 guest 容器内部 | 为一个工作区提供 exec/filesystem gRPC API |
15
+ | `dsh-podman-orchestrator` | 一个可访问 Podman API 的容器 | 持有 control socket 和持久化状态;创建/删除 guest 容器;构建工作区镜像 |
16
+ | `dsh-podman-gateway` | 由标准安装一并部署、运行在主机网络上的容器 | 将已发布的 pod 端口桥接到主机回环地址 |
16
17
 
17
18
  该插件会自动使用其配置的默认镜像和单个读写项目挂载来创建缺失的工作区;`container_mount_update`
18
19
  可将该挂载重新挂载为只读。它绝不会回退到主机执行。
@@ -131,6 +132,37 @@ pod 网络命名空间,因此在只读模式下被允许的命令可以通过
131
132
  重新创建容器或关闭 orchestrator 时,会先要求容器的 guest agent
132
133
  优雅地停止其守护进程(SIGTERM,约 10 秒宽限期),然后 podman 才会拆除该容器。
133
134
 
135
+ ## 端口发布
136
+
137
+ pod 内监听的守护进程无法从主机访问:每个 pod
138
+ 都有自己的网络命名空间,也不会发布任何端口。`container_publish_port`
139
+ 通过两段转发把一个 TCP 端口带出来:
140
+
141
+ ```
142
+ 客户端 -> <地址>:<端口> -> gateway -> UNIX 套接字(套接字根目录)-> guest agent -> 127.0.0.1:<pod 端口>
143
+ ```
144
+
145
+ **guest agent** 在容器自己的套接字目录中(与
146
+ orchestrator、插件共享,也就是它自己的 `guest.sock`
147
+ 所在目录)监听一个简短的确定性 UNIX 套接字,并把每个连接转发到 pod 内的
148
+ `127.0.0.1:<端口>`。**gateway**
149
+ 是由标准安装一并部署、运行在主机网络上的容器,挂载同一个套接字根目录,绑定
150
+ `127.0.0.1:<主机端口>`
151
+ 并转发到该套接字。它把地址和端口一起返回,因此工具可以给出
152
+ `tcp://127.0.0.1:6666`;地址由 gateway 决定,这也让将来的 HTTP
153
+ 发布可以返回主机名。
154
+
155
+ **orchestrator**
156
+ 负责整个生命周期:它把每个已发布端口记录在容器上,在容器重建后重新创建 guest
157
+ 套接字(gateway
158
+ 的绑定仍在,因此主机端口不会变化),并在取消发布、移除容器或销毁工作区时释放绑定。已发布端口的状态不会只存在于
159
+ gateway 中:只有在 orchestrator 保持租约流打开时 gateway 才持有绑定,因此
160
+ orchestrator 停止或崩溃不会留下主机端口,gateway 重启后也会从存储中重新绑定。
161
+
162
+ 目前只实现 TCP。线上格式、存储记录和返回的地址字符串都已带协议字段,因此将来增加
163
+ UDP 或 HTTP 无需改动它们。gateway
164
+ 是可选的:只有发布端口需要它,没有它时发布操作会报告其未运行,其他功能不受影响。
165
+
134
166
  ## 镜像
135
167
 
136
168
  orchestrator 通过 Podman 构建工作区镜像(有关原始/基础/自定义分层,请参阅
@@ -71,6 +71,7 @@ for secrets (see [Secrets](usage.md#secrets)).
71
71
  | `DSH_PODMAN_HOST_GUEST_AGENT_BIN` | — | Host-side guest agent binary path; bind-mounted when set; see [Variable details](#variable-details) |
72
72
  | `DSH_PODMAN_HOST_PACMAN_CACHE` | — | Host-absolute directory mounted at `/var/cache/pacman/pkg` to persist downloaded packages across pacman builds; unset disables caching |
73
73
  | `DSH_PODMAN_HOST_PROJECTS_ROOT` | `DSH_PODMAN_PROJECTS_ROOT` | Host-side projects root used as the source of bind mounts |
74
+ | `DSH_PODMAN_GATEWAY_TOKEN` | — | Optional shared secret for gateway calls (`orchestrator` → gateway); see [Variable details](#variable-details) |
74
75
  | `DSH_PODMAN_HOST_SOCKETS_ROOT` | required | Host-side sockets root for guest socket bind mounts; see [Variable details](#variable-details) |
75
76
  | `DSH_PODMAN_IMAGE_PREFIX` | `localhost/dsh-podman/` | Prefix prepended to built workspace image references |
76
77
  | `DSH_PODMAN_ORCHESTRATOR_PODMAN_SOCKET` | required | Podman API socket, e.g. `unix:///run/podman/podman.sock` |
@@ -89,6 +90,19 @@ for secrets (see [Secrets](usage.md#secrets)).
89
90
  | `DSH_PODMAN_GUEST_TOKEN` | — | Bearer token required on every gRPC call; see [Variable details](#variable-details) |
90
91
  | `DSH_PODMAN_PROJECTS_ROOT` | `/projects` | Root where the workspace's project(s) are mounted |
91
92
 
93
+ ## Gateway (`dsh-podman-gateway`)
94
+
95
+ | Variable | Default | Description |
96
+ | --------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------- |
97
+ | `DSH_PODMAN_GATEWAY_SOCKET` | `<sockets root>/gateway.sock` | Unix socket the gateway serves its control API on |
98
+ | `DSH_PODMAN_GATEWAY_SOCKETS_ROOT` | `/run/dsh-podman` | Shared socket root; the gateway reaches each container's published socket below it |
99
+ | `DSH_PODMAN_GATEWAY_TOKEN` | — | Optional bearer token required on every control call; see [Variable details](#variable-details) |
100
+
101
+ The standard install runs the gateway. It is optional — only publishing pod
102
+ ports needs it (see [Usage](usage.md#published-ports)) — and it binds
103
+ `127.0.0.1` and nothing else, so a published port is reachable from the host
104
+ alone.
105
+
92
106
  ## Variable details
93
107
 
94
108
  ### `DSH_PODMAN_BASE_IMAGE_PREFIX`
@@ -164,6 +178,17 @@ orchestrator has no token set, it accepts unauthenticated control-plane calls
164
178
  (relying on the socket's file permissions instead); when a token is set,
165
179
  requests without the matching header are rejected with `Unauthenticated`.
166
180
 
181
+ ### `DSH_PODMAN_GATEWAY_TOKEN`
182
+
183
+ An arbitrary shared secret string that the gateway and the orchestrator must
184
+ agree on; every gateway control call carries it as the gRPC metadata header
185
+ `authorization: bearer <token>`. Use a long, random value — for example
186
+ `openssl rand -hex 32` — and set the same value on both sides. When the gateway
187
+ has no token set, it accepts unauthenticated control calls (relying on the
188
+ socket's file permissions instead) and logs a warning; when a token is set,
189
+ calls without the matching header are rejected with `Unauthenticated`. The dsh
190
+ plugin does not talk to the gateway and does not need this variable.
191
+
167
192
  ### `DSH_PODMAN_ORCHESTRATOR_STATE`
168
193
 
169
194
  The directory the orchestrator persists its state in (workspaces, containers,
@@ -65,6 +65,7 @@ Podman
65
65
  | `DSH_PODMAN_HOST_GUEST_AGENT_BIN` | — | 主机侧的 guest agent 二进制路径;设置后会绑定挂载;见[变量详解](#变量详解) |
66
66
  | `DSH_PODMAN_HOST_PACMAN_CACHE` | — | 挂载在 `/var/cache/pacman/pkg` 的主机绝对路径目录,用于在 pacman 构建之间持久化已下载的软件包;未设置时禁用缓存 |
67
67
  | `DSH_PODMAN_HOST_PROJECTS_ROOT` | `DSH_PODMAN_PROJECTS_ROOT` | 用作绑定挂载源的主机侧项目根目录 |
68
+ | `DSH_PODMAN_GATEWAY_TOKEN` | — | gateway 调用(`orchestrator` → gateway)的可选共享机密;见[变量详解](#变量详解) |
68
69
  | `DSH_PODMAN_HOST_SOCKETS_ROOT` | required | 用于 guest 套接字绑定挂载的主机侧套接字根目录;见[变量详解](#变量详解) |
69
70
  | `DSH_PODMAN_IMAGE_PREFIX` | `localhost/dsh-podman/` | 前置到已构建的工作区镜像引用上的前缀 |
70
71
  | `DSH_PODMAN_ORCHESTRATOR_PODMAN_SOCKET` | required | Podman API 套接字,例如 `unix:///run/podman/podman.sock` |
@@ -83,6 +84,18 @@ Podman
83
84
  | `DSH_PODMAN_GUEST_TOKEN` | — | 每次 gRPC 调用所需的 Bearer 令牌;见[变量详解](#变量详解) |
84
85
  | `DSH_PODMAN_PROJECTS_ROOT` | `/projects` | 工作区的项目被挂载到的根目录 |
85
86
 
87
+ ## Gateway(`dsh-podman-gateway`)
88
+
89
+ | 变量 | 默认值 | 说明 |
90
+ | --------------------------------- | ----------------------------- | ------------------------------------------------------- |
91
+ | `DSH_PODMAN_GATEWAY_SOCKET` | `<套接字根目录>/gateway.sock` | gateway 提供控制 API 的 Unix 套接字 |
92
+ | `DSH_PODMAN_GATEWAY_SOCKETS_ROOT` | `/run/dsh-podman` | 共享套接字根目录;gateway 在其下访问各容器发布的套接字 |
93
+ | `DSH_PODMAN_GATEWAY_TOKEN` | — | 每次控制调用的可选 Bearer 令牌;见[变量详解](#变量详解) |
94
+
95
+ 标准安装会运行 gateway。它是可选的:只有发布 pod
96
+ 端口时才需要它(见[用法](usage.zh.md#端口发布))。它只绑定
97
+ `127.0.0.1`,因此已发布端口只能从本机访问。
98
+
86
99
  ## 变量详解
87
100
 
88
101
  ### `DSH_PODMAN_BASE_IMAGE_PREFIX`
@@ -147,6 +160,16 @@ orchestrator 和插件必须约定的任意共享机密字符串;每个控制
147
160
  未设置令牌时,它接受未经认证的控制平面调用(转而依赖套接字的文件权限);当设置了令牌时,不带匹配头的请求会被以
148
161
  `Unauthenticated` 拒绝。
149
162
 
163
+ ### `DSH_PODMAN_GATEWAY_TOKEN`
164
+
165
+ gateway 与 orchestrator 必须一致的任意共享机密字符串;每次 gateway
166
+ 控制调用都会以 gRPC 元数据标头 `authorization: bearer <token>`
167
+ 携带它。请使用足够长的随机值——例如
168
+ `openssl rand -hex
169
+ 32`——并在两端设置相同的值。gateway
170
+ 未设置令牌时会接受未经认证的控制调用(改由套接字文件权限保护)并记录一条警告;设置了令牌后,缺少匹配标头的调用会被拒绝并返回
171
+ `Unauthenticated`。dsh 插件不访问 gateway,因此不需要该变量。
172
+
150
173
  ### `DSH_PODMAN_ORCHESTRATOR_STATE`
151
174
 
152
175
  orchestrator
@@ -128,6 +128,13 @@ reference. The local build reuses a single `:latest` tag instead; the
128
128
  orchestrator then cannot tell that the agent was rebuilt, which is what
129
129
  [Update workspace containers](#update-workspace-containers) is about.
130
130
 
131
+ In `~/.config/containers/systemd/dsh-podman-gateway.container`:
132
+
133
+ ```ini
134
+ #Image=ghcr.io/exagone313/dsh-podman/gateway:1
135
+ Image=localhost/dsh-podman-gateway:latest
136
+ ```
137
+
131
138
  Reload systemd after editing the units:
132
139
 
133
140
  ```bash
@@ -138,9 +145,9 @@ systemctl --user daemon-reload
138
145
 
139
146
  ```bash
140
147
  make # Go binaries + the plugin bundle
141
- make image # orchestrator, guest-agent and dsh images
148
+ make image # orchestrator, guest-agent, gateway and dsh images
142
149
  npm pack # the plugin archive the dsh entrypoint installs
143
- systemctl --user restart dsh dsh-podman-orchestrator
150
+ systemctl --user restart dsh dsh-podman-orchestrator dsh-podman-gateway
144
151
  ```
145
152
 
146
153
  The dsh image installs the plugin at container start, so restarting dsh is what
@@ -122,6 +122,13 @@ Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=localhost/dsh-podman-guest-agent:latest
122
122
  `:latest` 标签;orchestrator 因此无法察觉 guest agent
123
123
  已被重建,详见[更新工作区容器](#更新工作区容器)。
124
124
 
125
+ 在 `~/.config/containers/systemd/dsh-podman-gateway.container` 中:
126
+
127
+ ```ini
128
+ #Image=ghcr.io/exagone313/dsh-podman/gateway:1
129
+ Image=localhost/dsh-podman-gateway:latest
130
+ ```
131
+
125
132
  编辑单元后重新加载 systemd:
126
133
 
127
134
  ```bash
@@ -132,9 +139,9 @@ systemctl --user daemon-reload
132
139
 
133
140
  ```bash
134
141
  make # Go binaries + the plugin bundle
135
- make image # orchestrator, guest-agent and dsh images
142
+ make image # orchestrator, guest-agent, gateway and dsh images
136
143
  npm pack # the plugin archive the dsh entrypoint installs
137
- systemctl --user restart dsh dsh-podman-orchestrator
144
+ systemctl --user restart dsh dsh-podman-orchestrator dsh-podman-gateway
138
145
  ```
139
146
 
140
147
  dsh 镜像会在容器启动时安装插件,因此重启 dsh 才会重新安装刚打包的归档;重启
@@ -47,6 +47,8 @@ could be added in the future.
47
47
  - **dsh-podman orchestrator**: the daemon that receives connections from the
48
48
  dsh-podman plugin, has access to the Podman socket and manages containers and
49
49
  other resources; it runs in a container; referred to later as _orchestrator_
50
+ - **dsh-podman gateway**: the host-network container that publishes guest pod
51
+ ports on the host's loopback; referred to later as _gateway_
50
52
  - **Podman socket**: while the Podman client can be used without a daemon, it is
51
53
  still possible to enable management through a socket, which is required by the
52
54
  orchestrator to work as if it were running on the host system
@@ -109,8 +111,9 @@ which requires online access.
109
111
  ```bash
110
112
  mkdir -p ~/.config/containers/systemd
111
113
  ```
112
- 2. Copy the files [dsh.container](../quadlet/dsh.container) and
114
+ 2. Copy the files [dsh.container](../quadlet/dsh.container),
113
115
  [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
116
+ and [dsh-podman-gateway.container](../quadlet/dsh-podman-gateway.container)
114
117
  to `~/.config/containers/systemd/`.
115
118
  ```bash
116
119
  cp quadlet/* ~/.config/containers/systemd/
@@ -124,17 +127,20 @@ which requires online access.
124
127
  ```bash
125
128
  journalctl --user -e
126
129
  ```
127
- 5. Start dsh and dsh-podman-orchestrator:
130
+ 5. Start dsh, dsh-podman-orchestrator and dsh-podman-gateway:
128
131
  ```bash
129
- systemctl --user start dsh dsh-podman-orchestrator
132
+ systemctl --user start dsh dsh-podman-orchestrator dsh-podman-gateway
130
133
  ```
131
- 6. Check if there are startup errors from either container:
134
+ 6. Check if there are startup errors from any container:
132
135
  ```bash
133
136
  journalctl --user -eu dsh
134
137
  ```
135
138
  ```bash
136
139
  journalctl --user -eu dsh-podman-orchestrator
137
140
  ```
141
+ ```bash
142
+ journalctl --user -eu dsh-podman-gateway
143
+ ```
138
144
  7. View the dsh container logs:
139
145
  ```bash
140
146
  podman logs dsh
@@ -37,6 +37,8 @@ SPDX-License-Identifier: MIT
37
37
  UI,并连接编排器;下文简称 _plugin_
38
38
  - **dsh-podman 编排器**:接收来自 dsh-podman 插件连接的守护进程,可访问 Podman
39
39
  套接字并管理容器和其他资源;它在容器中运行;下文简称 _orchestrator_
40
+ - **dsh-podman gateway**:运行在主机网络上的容器,把 guest pod
41
+ 端口发布到主机回环地址;下文简称 _gateway_
40
42
  - **Podman 套接字**:虽然 Podman
41
43
  客户端可以在没有守护进程的情况下使用,但仍然可以通过套接字启用管理,这是编排器以仿佛在主机系统上运行的方式工作所必需的
42
44
  - **guest 容器**:由 dsh-podman 编排器创建的容器,与 dsh 工作区相关联
@@ -90,8 +92,9 @@ SPDX-License-Identifier: MIT
90
92
  ```bash
91
93
  mkdir -p ~/.config/containers/systemd
92
94
  ```
93
- 2. 将文件 [dsh.container](../quadlet/dsh.container) 和
95
+ 2. 将文件 [dsh.container](../quadlet/dsh.container)、
94
96
  [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
97
+ 和 [dsh-podman-gateway.container](../quadlet/dsh-podman-gateway.container)
95
98
  复制到 `~/.config/containers/systemd/`。
96
99
  ```bash
97
100
  cp quadlet/* ~/.config/containers/systemd/
@@ -105,9 +108,9 @@ SPDX-License-Identifier: MIT
105
108
  ```bash
106
109
  journalctl --user -e
107
110
  ```
108
- 5. 启动 dsh 和 dsh-podman-orchestrator:
111
+ 5. 启动 dsh、dsh-podman-orchestrator 和 dsh-podman-gateway:
109
112
  ```bash
110
- systemctl --user start dsh dsh-podman-orchestrator
113
+ systemctl --user start dsh dsh-podman-orchestrator dsh-podman-gateway
111
114
  ```
112
115
  6. 检查任一容器是否有启动错误:
113
116
  ```bash
@@ -116,6 +119,9 @@ SPDX-License-Identifier: MIT
116
119
  ```bash
117
120
  journalctl --user -eu dsh-podman-orchestrator
118
121
  ```
122
+ ```bash
123
+ journalctl --user -eu dsh-podman-gateway
124
+ ```
119
125
  7. 查看 dsh 容器日志:
120
126
  ```bash
121
127
  podman logs dsh
package/docs/uninstall.md CHANGED
@@ -7,8 +7,8 @@ SPDX-License-Identifier: MIT
7
7
  # Uninstall
8
8
 
9
9
  This page undoes the [installation guide](install-dsh-and-dsh-podman.md): it
10
- assumes dsh runs from the dsh-podman image with the orchestrator, both started
11
- from Quadlet units.
10
+ assumes dsh runs from the dsh-podman image with the orchestrator and the
11
+ gateway, all started from Quadlet units.
12
12
 
13
13
  The dsh image installs the dsh-podman plugin at container start, and the
14
14
  plugin's bundle layer is what disables dsh's own `subprocess`, `fs-sandbox`,
@@ -20,9 +20,10 @@ dsh user, with no container isolation.
20
20
  ## Stop the containers and remove the Quadlet units
21
21
 
22
22
  ```bash
23
- systemctl --user stop dsh dsh-podman-orchestrator
23
+ systemctl --user stop dsh dsh-podman-orchestrator dsh-podman-gateway
24
24
  rm ~/.config/containers/systemd/dsh.container
25
25
  rm ~/.config/containers/systemd/dsh-podman-orchestrator.container
26
+ rm ~/.config/containers/systemd/dsh-podman-gateway.container
26
27
  systemctl --user daemon-reload
27
28
  ```
28
29
 
@@ -7,7 +7,7 @@ SPDX-License-Identifier: MIT
7
7
  # 卸载
8
8
 
9
9
  本页用于撤销[安装指南](install-dsh-and-dsh-podman.zh.md)中的操作:其中假设 dsh
10
- 运行在 dsh-podman 镜像中,并与编排器一同由 Quadlet 单元启动。
10
+ 运行在 dsh-podman 镜像中,并与编排器和 gateway 一同由 Quadlet 单元启动。
11
11
 
12
12
  dsh 镜像会在容器启动时安装 dsh-podman 插件,而该插件的 bundle 层正是禁用 dsh
13
13
  自带的 `subprocess`、`fs-sandbox`、`spill-local`
@@ -18,9 +18,10 @@ dsh-podman 运行 dsh:其内置的 shell 与文件系统工具会重新启用
18
18
  ## 停止容器并移除 Quadlet 单元
19
19
 
20
20
  ```bash
21
- systemctl --user stop dsh dsh-podman-orchestrator
21
+ systemctl --user stop dsh dsh-podman-orchestrator dsh-podman-gateway
22
22
  rm ~/.config/containers/systemd/dsh.container
23
23
  rm ~/.config/containers/systemd/dsh-podman-orchestrator.container
24
+ rm ~/.config/containers/systemd/dsh-podman-gateway.container
24
25
  systemctl --user daemon-reload
25
26
  ```
26
27
 
package/docs/update.md CHANGED
@@ -17,18 +17,35 @@ startup.
17
17
  When enabling auto-updates, it is possible to skip updates while an agent is
18
18
  running. Read further to set this up.
19
19
 
20
+ ## Update from before 1.1.0
21
+
22
+ The `dsh-podman-gateway` container is new in 1.1.0: earlier versions did not
23
+ ship its Quadlet. The gateway is optional and only needed to publish pod ports
24
+ (see [Usage](usage.md#published-ports)); without it, `container_publish_port`
25
+ fails with an error telling you to install and start the gateway Quadlet.
26
+
27
+ When you update from a version before 1.1.0, copy
28
+ [dsh-podman-gateway.container](../quadlet/dsh-podman-gateway.container) to
29
+ `~/.config/containers/systemd/` and start it once, before the steps below:
30
+
31
+ ```bash
32
+ cp quadlet/dsh-podman-gateway.container ~/.config/containers/systemd/
33
+ systemctl --user daemon-reload
34
+ systemctl --user start dsh-podman-gateway
35
+ ```
36
+
20
37
  ## Update manually
21
38
 
22
39
  Pull the new images:
23
40
 
24
41
  ```bash
25
- podman pull ghcr.io/exagone313/dsh-podman/dsh:1 ghcr.io/exagone313/dsh-podman/orchestrator:1
42
+ podman pull ghcr.io/exagone313/dsh-podman/dsh:1 ghcr.io/exagone313/dsh-podman/orchestrator:1 ghcr.io/exagone313/dsh-podman/gateway:1
26
43
  ```
27
44
 
28
- Restart dsh and dsh-podman-orchestrator:
45
+ Restart dsh, dsh-podman-orchestrator and dsh-podman-gateway:
29
46
 
30
47
  ```bash
31
- systemctl --user restart dsh dsh-podman-orchestrator
48
+ systemctl --user restart dsh dsh-podman-orchestrator dsh-podman-gateway
32
49
  ```
33
50
 
34
51
  ## Upgrade to a new major version
@@ -39,9 +56,9 @@ above, check the
39
56
 
40
57
  ## Enable auto-updates
41
58
 
42
- The quadlet configuration for dsh and dsh-podman-orchestrator enables
43
- auto-update of images (`AutoUpdate=registry`). The `podman-auto-update` systemd
44
- timer needs to be enabled for this to work:
59
+ The quadlet configuration for dsh, dsh-podman-orchestrator and
60
+ dsh-podman-gateway enables auto-update of images (`AutoUpdate=registry`). The
61
+ `podman-auto-update` systemd timer needs to be enabled for this to work:
45
62
 
46
63
  ```bash
47
64
  systemctl --user enable --now podman-auto-update.timer