Skaffold with OrbStack - Port-Forward-Free Development

结合OrbStack使用Skaffold——无需端口转发的开发体验

Overview

概述

OrbStack provides superior local Kubernetes networking compared to other tools (minikube, kind, Docker Desktop). Services are accessible directly from macOS without port-forward.

与其他工具（minikube、kind、Docker Desktop）相比，OrbStack提供了更出色的本地Kubernetes网络能力。在macOS上无需端口转发即可直接访问服务。

Key OrbStack Advantages

OrbStack的核心优势

Feature	OrbStack	minikube/kind
LoadBalancer auto-provision	✅ Yes	❌ Needs MetalLB
Wildcard DNS ( `*.k8s.orb.local` )	✅ Yes	❌ No
cluster.local from host	✅ Yes	❌ No
Pod IP direct access	✅ Yes	❌ No
Auto HTTPS certificates	✅ Yes	❌ No

特性	OrbStack	minikube/kind
LoadBalancer自动配置	✅ 支持	❌ 需要MetalLB
通配符DNS（ `*.k8s.orb.local` ）	✅ 支持	❌ 不支持
从主机访问cluster.local	✅ 支持	❌ 不支持
直接访问Pod IP	✅ 支持	❌ 不支持
自动HTTPS证书	✅ 支持	❌ 不支持

Service Access Methods

服务访问方式

Method 1: LoadBalancer Services (Simplest)

方式1：LoadBalancer服务（最简单）

Change service type from ClusterIP to LoadBalancer:

yaml

apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: LoadBalancer  # OrbStack auto-provisions external IP
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: my-app

Access:

curl http://my-app.default.svc.cluster.local

from macOS

将服务类型从ClusterIP改为LoadBalancer：

yaml

apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: LoadBalancer  # OrbStack自动配置外部IP
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: my-app

访问方式：在macOS上执行

curl http://my-app.default.svc.cluster.local

Method 2: Ingress with Wildcard DNS (Recommended)

方式2：结合通配符DNS使用Ingress（推荐）

One-time setup - Install Ingress controller:

bash

undefined

一次性配置 - 安装Ingress控制器：

bash

undefined

Ingress-NGINX (recommended)

Ingress-NGINX（推荐）

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml

OR Traefik

或Traefik

helm repo add traefik https://traefik.github.io/charts helm install traefik traefik/traefik


**Create Ingress for your service:**

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
spec:
  ingressClassName: nginx
  rules:
    - host: my-app.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

Access:

http://my-app.k8s.orb.local

(auto-resolves)

helm repo add traefik https://traefik.github.io/charts helm install traefik traefik/traefik


**为你的服务创建Ingress：**

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
spec:
  ingressClassName: nginx
  rules:
    - host: my-app.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

访问方式：

http://my-app.k8s.orb.local

（自动解析）

Method 3: Direct Service DNS (cluster.local)

方式3：直接使用服务DNS（cluster.local）

OrbStack exposes cluster DNS to macOS:

bash

undefined

OrbStack将集群DNS暴露给macOS：

bash

undefined

Access any service directly

直接访问任意服务

curl http://my-app.default.svc.cluster.local:8080

Full DNS pattern

完整DNS格式

curl http://<service>.<namespace>.svc.cluster.local:<port>

undefined

curl http://<service>.<namespace>.svc.cluster.local:<port>

undefined

Skaffold Configuration for OrbStack

针对OrbStack的Skaffold配置

Minimal skaffold.yaml (No Port-Forward Needed)

极简skaffold.yaml（无需端口转发）

yaml

apiVersion: skaffold/v4beta11
kind: Config
metadata:
  name: my-app

build:
  local:
    push: false
    useBuildkit: true
  artifacts:
    - image: my-app
      docker:
        dockerfile: Dockerfile

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml
  statusCheck: true
  statusCheckDeadlineSeconds: 180

yaml

apiVersion: skaffold/v4beta11
kind: Config
metadata:
  name: my-app

build:
  local:
    push: false
    useBuildkit: true
  artifacts:
    - image: my-app
      docker:
        dockerfile: Dockerfile

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml
  statusCheck: true
  statusCheckDeadlineSeconds: 180

Port-forward REMOVED - use LoadBalancer/Ingress instead

已移除端口转发 - 改用LoadBalancer/Ingress

undefined

undefined

Profile: Local with Ingress

配置文件：本地Ingress模式

yaml

profiles:
  - name: local-ingress
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/base/*.yaml
          - k8s/ingress/*.yaml  # Ingress resources

yaml

profiles:
  - name: local-ingress
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/base/*.yaml
          - k8s/ingress/*.yaml  # Ingress资源

Profile: Services-Only (Frontend Local Dev)

配置文件：仅服务模式（前端本地开发）

yaml

profiles:
  - name: services-only
    build:
      artifacts: []  # Don't build frontend
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/namespace.yaml
          - k8s/database/*.yaml
          - k8s/api/*.yaml

Access backend at

http://api.k8s.orb.local

while running

npm run dev

locally.

yaml

profiles:
  - name: services-only
    build:
      artifacts: []  # 不构建前端
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/namespace.yaml
          - k8s/database/*.yaml
          - k8s/api/*.yaml

在本地运行

npm run dev

时，可通过

http://api.k8s.orb.local

访问后端。

Kubernetes Manifest Templates

Kubernetes清单模板

LoadBalancer Service Template

LoadBalancer服务模板

yaml

undefined

yaml

undefined

k8s/service.yaml

apiVersion: v1 kind: Service metadata: name: {{ .name }} labels: app: {{ .name }} spec: type: LoadBalancer ports: - name: http port: 80 targetPort: {{ .containerPort | default 8080 }} selector: app: {{ .name }}

undefined

apiVersion: v1 kind: Service metadata: name: {{ .name }} labels: app: {{ .name }} spec: type: LoadBalancer ports: - name: http port: 80 targetPort: {{ .containerPort | default 8080 }} selector: app: {{ .name }}

undefined

Ingress Template

Ingress模板

yaml

undefined

yaml

undefined

k8s/ingress.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: {{ .name }} annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: ingressClassName: nginx rules: - host: {{ .name }}.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: {{ .name }} port: number: 80

undefined

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: {{ .name }} annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: ingressClassName: nginx rules: - host: {{ .name }}.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: {{ .name }} port: number: 80

undefined

Migration: Port-Forward to LoadBalancer

迁移：从端口转发到LoadBalancer

Before (Traditional)

之前（传统方式）

yaml

undefined

yaml

undefined

skaffold.yaml with port-forward

带端口转发的skaffold.yaml

portForward:

resourceType: service resourceName: api port: 8080 localPort: 8080 address: 127.0.0.1
resourceType: service resourceName: frontend port: 3000 localPort: 3000 address: 127.0.0.1


```bash
skaffold dev  # Services at localhost:8080, localhost:3000

portForward:

resourceType: service resourceName: api port: 8080 localPort: 8080 address: 127.0.0.1
resourceType: service resourceName: frontend port: 3000 localPort: 3000 address: 127.0.0.1


```bash
skaffold dev  # 服务可通过localhost:8080、localhost:3000访问

After (OrbStack Native)

之后（OrbStack原生方式）

yaml

undefined

yaml

undefined

k8s/services.yaml - Change service types

k8s/services.yaml - 修改服务类型

apiVersion: v1 kind: Service metadata: name: api spec: type: LoadBalancer # Changed from ClusterIP ports: - port: 8080

apiVersion: v1 kind: Service metadata: name: frontend spec: type: LoadBalancer # Changed from ClusterIP ports: - port: 3000


```yaml

apiVersion: v1 kind: Service metadata: name: api spec: type: LoadBalancer # 从ClusterIP修改而来 ports: - port: 8080

apiVersion: v1 kind: Service metadata: name: frontend spec: type: LoadBalancer # 从ClusterIP修改而来 ports: - port: 3000


```yaml

skaffold.yaml - Remove portForward section entirely

skaffold.yaml - 完全移除portForward部分

deploy: kubeContext: orbstack kubectl: manifests: - k8s/*.yaml

No portForward needed!

无需portForward！


```bash
skaffold dev  # Services at api.default.svc.cluster.local:8080
              #            frontend.default.svc.cluster.local:3000


```bash
skaffold dev  # 服务可通过api.default.svc.cluster.local:8080
              #            frontend.default.svc.cluster.local:3000访问

Common Patterns

常见模式

Database Access

数据库访问

yaml

undefined

yaml

undefined

k8s/postgresql.yaml

apiVersion: v1 kind: Service metadata: name: postgresql spec: type: LoadBalancer # Access from local tools (DBeaver, pgAdmin) ports: - port: 5432


**Connection string**: `postgres://user:pass@postgresql.default.svc.cluster.local:5432/db`  <!-- pragma: allowlist secret -->

apiVersion: v1 kind: Service metadata: name: postgresql spec: type: LoadBalancer # 可从本地工具（DBeaver、pgAdmin）访问 ports: - port: 5432


**连接字符串**：`postgres://user:pass@postgresql.default.svc.cluster.local:5432/db`  <!-- pragma: allowlist secret -->

Multi-Service Application

多服务应用

yaml

undefined

yaml

undefined

k8s/ingress.yaml - Single Ingress for all services

k8s/ingress.yaml - 为所有服务配置单个Ingress

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-ingress spec: ingressClassName: nginx rules: - host: api.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: api port: number: 8080 - host: web.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: frontend port: number: 3000 - host: admin.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: admin-panel port: number: 8000

undefined

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-ingress spec: ingressClassName: nginx rules: - host: api.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: api port: number: 8080 - host: web.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: frontend port: number: 3000 - host: admin.k8s.orb.local http: paths: - path: / pathType: Prefix backend: service: name: admin-panel port: number: 8000

undefined

Security Considerations

安全注意事项

Default: Localhost Only

默认：仅本地主机可访问

OrbStack restricts services to localhost by default - safe on untrusted networks.

OrbStack默认将服务限制为仅本地主机可访问——在不可信网络中也能保证安全。

Expose to LAN (Use with Caution)

暴露到局域网（谨慎使用）

Settings → Kubernetes → "Expose services to local network devices"

Only enable when:

Testing from mobile devices on same network
Sharing local environment with team
On trusted network

设置 → Kubernetes → "将服务暴露给本地网络设备"

仅在以下场景启用：

在同一网络的移动设备上测试
与团队共享本地环境
在可信网络中

Troubleshooting

故障排查

Service Not Accessible

服务无法访问

Check service type:
```
kubectl get svc
```
Verify LoadBalancer has EXTERNAL-IP (not
```
<pending>
```
)

Test DNS:

nslookup my-app.default.svc.cluster.local

检查服务类型：
```
kubectl get svc
```
验证LoadBalancer是否有EXTERNAL-IP（不是
```
<pending>
```
）

测试DNS：

nslookup my-app.default.svc.cluster.local

Ingress Not Working

Ingress无法工作

Verify Ingress controller is running:
bash
```
kubectl -n ingress-nginx get pods
```
Check Ingress controller has LoadBalancer IP:
bash
```
kubectl -n ingress-nginx get svc
```
Verify Ingress resource:
bash
```
kubectl describe ingress my-app
```

验证Ingress控制器是否在运行：
bash
```
kubectl -n ingress-nginx get pods
```
检查Ingress控制器是否有LoadBalancer IP：
bash
```
kubectl -n ingress-nginx get svc
```
验证Ingress资源：
bash
```
kubectl describe ingress my-app
```

DNS Resolution Issues

DNS解析问题

bash

undefined

bash

undefined

Test cluster DNS from macOS

在macOS上测试集群DNS

nslookup my-service.default.svc.cluster.local

If short names fail, use full domain

如果短名称解析失败，请使用完整域名

❌ my-service.default.svc

✅ my-service.default.svc.cluster.local

undefined

undefined

Pod IP Direct Access (Debugging)

直接访问Pod IP（调试用）

bash

undefined

bash

undefined

Get pod IP

获取Pod IP

kubectl get pods -o wide

Connect directly (OrbStack routes pod network to macOS)

直接连接（OrbStack将Pod网络路由到macOS）

curl http://10.42.0.15:8080

undefined

curl http://10.42.0.15:8080

undefined

Quick Setup Checklist

快速设置检查清单

Install Ingress controller (one-time)
Change service types to LoadBalancer
Create Ingress resources for pretty URLs
Remove
```
portForward
```
from skaffold.yaml
Set
```
kubeContext: orbstack
```
in deploy config
Update local .env/config to use
```
.k8s.orb.local
```
URLs

安装Ingress控制器（一次性操作）
将服务类型改为LoadBalancer
创建Ingress资源以使用友好URL
从skaffold.yaml中移除
```
portForward
```
在部署配置中设置
```
kubeContext: orbstack
```
更新本地.env/配置文件以使用
```
.k8s.orb.local
```
域名

Commands Reference

命令参考

bash

undefined

bash

undefined

Start development (no --port-forward needed)

启动开发环境（无需--port-forward参数）

skaffold dev --kube-context=orbstack

Run specific profile

运行指定配置文件

skaffold dev -p services-only --kube-context=orbstack

Check service accessibility

检查服务可访问性

kubectl get svc -o wide

Verify Ingress

验证Ingress

kubectl get ingress

undefined

kubectl get ingress

undefined

skaffold-orbstack

Original

Translation

Skaffold with OrbStack - Port-Forward-Free Development

结合OrbStack使用Skaffold——无需端口转发的开发体验

Overview

概述

Key OrbStack Advantages

OrbStack的核心优势

Service Access Methods

服务访问方式

Method 1: LoadBalancer Services (Simplest)

方式1：LoadBalancer服务（最简单）

Method 2: Ingress with Wildcard DNS (Recommended)

方式2：结合通配符DNS使用Ingress（推荐）

Ingress-NGINX (recommended)

Ingress-NGINX（推荐）

OR Traefik

或Traefik

Method 3: Direct Service DNS (cluster.local)

方式3：直接使用服务DNS（cluster.local）

Access any service directly

直接访问任意服务

Full DNS pattern

完整DNS格式

Skaffold Configuration for OrbStack

针对OrbStack的Skaffold配置

Minimal skaffold.yaml (No Port-Forward Needed)

极简skaffold.yaml（无需端口转发）

Port-forward REMOVED - use LoadBalancer/Ingress instead

已移除端口转发 - 改用LoadBalancer/Ingress

Profile: Local with Ingress

配置文件：本地Ingress模式

Profile: Services-Only (Frontend Local Dev)

配置文件：仅服务模式（前端本地开发）

Kubernetes Manifest Templates

Kubernetes清单模板

LoadBalancer Service Template

LoadBalancer服务模板

k8s/service.yaml

k8s/service.yaml

Ingress Template

Ingress模板

k8s/ingress.yaml

k8s/ingress.yaml

Migration: Port-Forward to LoadBalancer

迁移：从端口转发到LoadBalancer

Before (Traditional)

之前（传统方式）

skaffold.yaml with port-forward

带端口转发的skaffold.yaml

After (OrbStack Native)

之后（OrbStack原生方式）

k8s/services.yaml - Change service types

k8s/services.yaml - 修改服务类型

apiVersion: v1 kind: Service metadata: name: api spec: type: LoadBalancer # Changed from ClusterIP ports: - port: 8080

apiVersion: v1 kind: Service metadata: name: api spec: type: LoadBalancer # 从ClusterIP修改而来 ports: - port: 8080

skaffold.yaml - Remove portForward section entirely

skaffold.yaml - 完全移除portForward部分

No portForward needed!

无需portForward！

Common Patterns

常见模式

Database Access

数据库访问

k8s/postgresql.yaml

k8s/postgresql.yaml

Multi-Service Application

多服务应用

k8s/ingress.yaml - Single Ingress for all services

k8s/ingress.yaml - 为所有服务配置单个Ingress

Security Considerations

安全注意事项

Default: Localhost Only

默认：仅本地主机可访问

Expose to LAN (Use with Caution)

暴露到局域网（谨慎使用）

Troubleshooting

故障排查

Service Not Accessible