mcpField
S
skaffold-orbstack

skaffold-orbstack

github.com/laurigates云与 DevOps5960 次安装1 天前更新
代码仓库

关于 skaffold-orbstack

面向在 OrbStack 本地 Kubernetes 集群中使用 Skaffold 的开发者，介绍无需端口转发访问服务的配置方法。内容涵盖 LoadBalancer、Ingress、集群 DNS 及迁移和排错步骤。

主要功能

  1. 01配置 Skaffold 使用 OrbStack 集群
  2. 02通过 LoadBalancer 访问服务
  3. 03使用通配符 DNS 和 Ingress
  4. 04迁移端口转发配置
  5. 05排查服务与 DNS 问题

适用场景

  1. 01从 macOS 访问本地集群服务
  2. 02使用 Ingress 配置本地服务地址
  3. 03将 Skaffold 项目迁离端口转发
  4. 04从本地工具连接集群数据库

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laurigates/claude-plugins --skill skaffold-orbstack

安装后在 Claude Code 中输入/skaffold-orbstack确认已加载。

详细介绍

使用 OrbStack 运行 Skaffold——无需端口转发的开发

何时使用此技能

在以下情况下使用此技能……在以下情况下改用相关的 Skaffold/容器技能……
将 Skaffold 连接到 OrbStack 本地 Kubernetes 集群为内部开发循环定义文件同步规则（skaffold-filesync）
通过 *.k8s.orb.local、LoadBalancer 或 Ingress 访问服务，无需端口转发添加部署前的 test 或部署后的 verify 阶段（skaffold-testing）
将现有项目从 kubectl port-forward 迁移到 OrbStack 网络加固或缩小容器镜像本身（container-development）

概述

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

OrbStack 的主要优势

功能OrbStackminikube/kind
自动配置 LoadBalancer✅ 是❌ 需要 MetalLB
通配符 DNS（*.k8s.orb.local）✅ 是❌ 否
从主机访问 cluster.local✅ 是❌ 否
直接访问 Pod IP✅ 是❌ 否
自动 HTTPS 证书✅ 是❌ 否

服务访问方式

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

将服务类型从 ClusterIP 改为 LoadBalancer：

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

访问方式：在 macOS 上运行 curl http://my-app.default.svc.cluster.local

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

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

# Ingress-NGINX (recommended)
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml

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

为服务创建 Ingress：

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（自动解析）

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

OrbStack 会将集群 DNS 暴露给 macOS：

# Access any service directly
curl http://my-app.default.svc.cluster.local:8080

# Full DNS pattern
curl http://<service>.<namespace>.svc.cluster.local:<port>

OrbStack 的 Skaffold 配置

最简 skaffold.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
配置文件：本地 Ingress
profiles:
  - name: local-ingress
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/base/*.yaml
          - k8s/ingress/*.yaml  # Ingress resources
配置文件：仅服务（前端本地开发）
profiles:
  - name: services-only
    build:
      artifacts: []  # Don't build frontend
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/namespace.yaml
          - k8s/database/*.yaml
          - k8s/api/*.yaml

本地运行 npm run dev 时，可通过 http://api.k8s.orb.local 访问后端。

Kubernetes 清单模板

LoadBalancer 服务模板
# 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 }}
Ingress 模板
# 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

迁移：从端口转发到 LoadBalancer

之前（传统方式）
# skaffold.yaml with port-forward
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

skaffold dev  # Services at localhost:8080, localhost:3000
之后（OrbStack 原生方式）
# k8s/services.yaml - Change service types
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

# skaffold.yaml - Remove portForward section entirely
deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml
# No portForward needed!

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

常见模式

数据库访问
# k8s/postgresql.yaml
apiVersion: v1
kind: Service
metadata:
  name: postgresql
spec:
  type: LoadBalancer  # Access from local tools (DBeaver, pgAdmin)
  ports:
    - port: 5432

连接字符串：postgres://user:[email protected]:5432/db

多服务应用
# k8s/ingress.yaml - Single Ingress for all services
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

安全注意事项

默认设置：仅限本地主机

默认情况下，OrbStack 会将服务限制在本地主机上，因此在不受信任的网络中也安全。

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

设置 → Kubernetes →“向本地网络设备暴露服务”

仅在以下情况下启用：

  • 从同一网络中的移动设备进行测试
  • 与团队共享本地环境
  • 位于受信任的网络中

故障排除

无法访问服务
  1. 检查服务类型：kubectl get svc
  2. 确认 LoadBalancer 有 EXTERNAL-IP（而不是 <pending>）
  3. 测试 DNS：nslookup my-app.default.svc.cluster.local
Ingress 无法正常工作
  1. 确认 Ingress 控制器正在运行： 
    kubectl -n ingress-nginx get pods
  2. 检查 Ingress 控制器是否有 LoadBalancer IP： 
    kubectl -n ingress-nginx get svc
  3. 确认 Ingress 资源： 
    kubectl describe ingress my-app
DNS 解析问题
# Test cluster DNS from macOS
nslookup my-service.default.svc.cluster.local

# If short names fail, use full domain
# ❌ my-service.default.svc
# ✅ my-service.default.svc.cluster.local
直接访问 Pod IP（调试）
# Get pod IP
kubectl get pods -o wide

# Connect directly (OrbStack routes pod network to macOS)
curl http://10.42.0.15:8080

Agentic 优化

场景命令
启动开发环境（无需端口转发）skaffold dev --kube-context=orbstack
检查服务 IPkubectl get svc -o wide
验证 Ingresskubectl get ingress
测试 DNS 解析nslookup my-app.default.svc.cluster.local
检查 Ingress 控制器kubectl -n ingress-nginx get pods
获取 Pod IPkubectl get pods -o wide
运行指定配置文件skaffold dev -p services-only --kube-context=orbstack
描述 Ingresskubectl describe ingress my-app

快速设置清单

  1. 安装 Ingress 控制器（一次性操作）
  2. 将服务类型改为 LoadBalancer
  3. 创建 Ingress 资源以使用简洁 URL
  4. 从 skaffold.yaml 中移除 portForward
  5. 在部署配置中设置 kubeContext: orbstack
  6. 更新本地 .env/配置，使用 .k8s.orb.local URL

命令参考

# Start development (no --port-forward needed)
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
kubectl get ingress

评论

支持 Markdown