@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.
- package/README.md +1 -0
- package/README.zh.md +1 -0
- package/dist/approval-reasons.d.ts +12 -0
- package/dist/approval-reasons.js +15 -0
- package/dist/approval.js +21 -0
- package/dist/card-route.js +83 -1
- package/dist/client/ContainerCard.js +14 -2
- package/dist/client/card-protocol.d.ts +16 -1
- package/dist/client/container-card-controller.d.ts +8 -2
- package/dist/client/container-card-controller.js +21 -0
- package/dist/client/container-card-ports.d.ts +13 -0
- package/dist/client/container-card-ports.js +74 -0
- package/dist/client/container-card-row.d.ts +3 -0
- package/dist/client/container-card-row.js +12 -2
- package/dist/client/container-card-workspace.d.ts +3 -0
- package/dist/client/container-card-workspace.js +2 -2
- package/dist/client/index.js +653 -386
- package/dist/client/locales.d.ts +1 -1
- package/dist/client/locales.js +30 -0
- package/dist/client/tool-presentations.d.ts +167 -0
- package/dist/client/tool-presentations.js +167 -0
- package/dist/client/tool-views.d.ts +1 -2
- package/dist/client/tool-views.js +54 -190
- package/dist/generated/version.d.ts +2 -2
- package/dist/generated/version.js +2 -2
- package/dist/grpc/proto/dshctl/v1/control.proto +47 -1
- package/dist/grpc/proto/dshgateway/v1/gateway.proto +89 -0
- package/dist/grpc/proto/dshguest/v1/guest.proto +17 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/public.d.ts +1 -0
- package/dist/public.js +14 -0
- package/dist/publish-port.d.ts +6 -0
- package/dist/publish-port.js +37 -0
- package/dist/tool-defs.js +15 -1
- package/dist/tool-handlers.js +31 -1
- package/dist/tool-params.d.ts +48 -0
- package/dist/tool-params.js +42 -0
- package/docs/architecture.md +44 -7
- package/docs/architecture.zh.md +38 -6
- package/docs/configuration.md +25 -0
- package/docs/configuration.zh.md +23 -0
- package/docs/development.md +9 -2
- package/docs/development.zh.md +9 -2
- package/docs/install-dsh-and-dsh-podman.md +10 -4
- package/docs/install-dsh-and-dsh-podman.zh.md +9 -3
- package/docs/uninstall.md +4 -3
- package/docs/uninstall.zh.md +3 -2
- package/docs/update.md +23 -6
- package/docs/update.zh.md +23 -6
- package/docs/usage.md +48 -13
- package/docs/usage.zh.md +31 -2
- package/package.json +1 -1
- package/quadlet/dsh-podman-gateway.container +23 -0
- package/quadlet/dsh-podman-orchestrator.container +1 -1
- package/quadlet/dsh.container +1 -1
package/dist/tool-handlers.js
CHANGED
|
@@ -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);
|
package/dist/tool-params.d.ts
CHANGED
|
@@ -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: {
|
package/dist/tool-params.js
CHANGED
|
@@ -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: {
|
package/docs/architecture.md
CHANGED
|
@@ -6,13 +6,14 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Architecture
|
|
8
8
|
|
|
9
|
-
dsh-podman has
|
|
9
|
+
dsh-podman has four components:
|
|
10
10
|
|
|
11
|
-
| Component | Runs
|
|
12
|
-
| ------------------------- |
|
|
13
|
-
| `@exagone313/dsh-podman` | Inside dsh itself
|
|
14
|
-
| `dsh-podman-guest-agent` | Inside every guest container
|
|
15
|
-
| `dsh-podman-orchestrator` | A container with access to the Podman API
|
|
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
|
package/docs/architecture.zh.md
CHANGED
|
@@ -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 内部
|
|
14
|
-
| `dsh-podman-guest-agent` | 每个 guest 容器内部
|
|
15
|
-
| `dsh-podman-orchestrator` | 一个可访问 Podman API 的容器
|
|
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 构建工作区镜像(有关原始/基础/自定义分层,请参阅
|
package/docs/configuration.md
CHANGED
|
@@ -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,
|
package/docs/configuration.zh.md
CHANGED
|
@@ -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
|
package/docs/development.md
CHANGED
|
@@ -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
|
package/docs/development.zh.md
CHANGED
|
@@ -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)
|
|
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-
|
|
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
|
|
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-
|
|
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
|
|
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
|
|
package/docs/uninstall.zh.md
CHANGED
|
@@ -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
|
|
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-
|
|
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
|
|
43
|
-
auto-update of images (`AutoUpdate=registry`). The
|
|
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
|